From 148f916c465b8559639fd2473571a0ccb4d65e29 Mon Sep 17 00:00:00 2001 From: ebembi-crdb Date: Tue, 12 May 2026 18:55:30 +0530 Subject: [PATCH] Replace remote_include with vendored includes Vendor 88 machine-generated doc files from cockroachdb/cockroach into _includes/cockroach-generated/ and update 55 versioned pages to use local {% include %} instead of {% remote_include %} directives. This eliminates runtime dependencies on raw.githubusercontent.com for generated reference docs (cluster settings, event log, functions and operators, log formats, logging). Part of DOC-17061. Co-Authored-By: Claude Opus 4.6 --- .../release-23.1/eventlog.md | 3216 +++++++++++++ .../release-23.1/logformats.md | 550 +++ .../release-23.1/logging.md | 179 + .../release-23.1/settings/settings.html | 271 ++ .../release-23.1/sql/aggregates.md | 519 +++ .../release-23.1/sql/functions.md | 3623 +++++++++++++++ .../release-23.1/sql/operators.md | 610 +++ .../release-23.1/sql/window_functions.md | 377 ++ .../release-23.2/eventlog.md | 3314 ++++++++++++++ .../release-23.2/logformats.md | 382 ++ .../release-23.2/logging.md | 179 + .../release-23.2/settings/settings.html | 293 ++ .../release-23.2/sql/aggregates.md | 531 +++ .../release-23.2/sql/functions.md | 3436 ++++++++++++++ .../release-23.2/sql/operators.md | 635 +++ .../release-23.2/sql/window_functions.md | 413 ++ .../release-24.1/eventlog.md | 3290 ++++++++++++++ .../release-24.1/logformats.md | 382 ++ .../release-24.1/logging.md | 179 + .../release-24.1/settings/settings.html | 310 ++ .../release-24.1/sql/aggregates.md | 579 +++ .../release-24.1/sql/functions.md | 3504 +++++++++++++++ .../release-24.1/sql/operators.md | 635 +++ .../release-24.1/sql/window_functions.md | 413 ++ .../release-24.2/eventlog.md | 3341 ++++++++++++++ .../release-24.2/logformats.md | 382 ++ .../release-24.2/logging.md | 179 + .../release-24.2/settings/settings.html | 315 ++ .../release-24.2/sql/aggregates.md | 579 +++ .../release-24.2/sql/functions.md | 3523 +++++++++++++++ .../release-24.2/sql/operators.md | 658 +++ .../release-24.2/sql/window_functions.md | 413 ++ .../release-24.3/eventlog.md | 3436 ++++++++++++++ .../release-24.3/logformats.md | 382 ++ .../release-24.3/logging.md | 179 + .../release-24.3/settings/settings.html | 371 ++ .../release-24.3/sql/aggregates.md | 579 +++ .../release-24.3/sql/functions.md | 3523 +++++++++++++++ .../release-24.3/sql/operators.md | 658 +++ .../release-24.3/sql/window_functions.md | 413 ++ .../release-25.1/eventlog.md | 3436 ++++++++++++++ .../release-25.1/logformats.md | 382 ++ .../release-25.1/logging.md | 179 + .../release-25.1/settings/settings.html | 371 ++ .../release-25.1/sql/aggregates.md | 579 +++ .../release-25.1/sql/functions.md | 3523 +++++++++++++++ .../release-25.1/sql/operators.md | 662 +++ .../release-25.1/sql/window_functions.md | 413 ++ .../release-25.2/eventlog.md | 3526 +++++++++++++++ .../release-25.2/logformats.md | 382 ++ .../release-25.2/logging.md | 179 + .../release-25.2/settings/settings.html | 383 ++ .../release-25.2/sql/aggregates.md | 579 +++ .../release-25.2/sql/functions.md | 3611 +++++++++++++++ .../release-25.2/sql/operators.md | 663 +++ .../release-25.2/sql/window_functions.md | 413 ++ .../release-25.3/eventlog.md | 3549 +++++++++++++++ .../release-25.3/logformats.md | 382 ++ .../release-25.3/logging.md | 179 + .../release-25.3/settings/settings.html | 380 ++ .../release-25.3/sql/aggregates.md | 579 +++ .../release-25.3/sql/functions.md | 3616 +++++++++++++++ .../release-25.3/sql/operators.md | 664 +++ .../release-25.3/sql/window_functions.md | 413 ++ .../release-25.4/eventlog.md | 3839 ++++++++++++++++ .../release-25.4/logformats.md | 382 ++ .../release-25.4/logging.md | 188 + .../release-25.4/settings/settings.html | 391 ++ .../release-25.4/sql/aggregates.md | 589 +++ .../release-25.4/sql/functions.md | 3669 +++++++++++++++ .../release-25.4/sql/operators.md | 684 +++ .../release-25.4/sql/window_functions.md | 431 ++ .../release-26.1/eventlog.md | 3874 ++++++++++++++++ .../release-26.1/logformats.md | 382 ++ .../release-26.1/logging.md | 188 + .../release-26.1/settings/settings.html | 396 ++ .../release-26.1/sql/aggregates.md | 589 +++ .../release-26.1/sql/functions.md | 3680 +++++++++++++++ .../release-26.1/sql/operators.md | 684 +++ .../release-26.1/sql/window_functions.md | 431 ++ .../release-26.2/eventlog.md | 4001 +++++++++++++++++ .../release-26.2/logformats.md | 382 ++ .../release-26.2/logging.md | 188 + .../release-26.2/settings/settings.html | 411 ++ .../release-26.2/sql/aggregates.md | 599 +++ .../release-26.2/sql/functions.md | 3732 +++++++++++++++ .../release-26.2/sql/operators.md | 684 +++ .../release-26.2/sql/window_functions.md | 431 ++ src/current/v23.1/cluster-settings.md | 2 +- src/current/v23.1/eventlog.md | 2 +- src/current/v23.1/functions-and-operators.md | 8 +- src/current/v23.1/log-formats.md | 2 +- src/current/v23.1/logging.md | 2 +- src/current/v23.2/cluster-settings.md | 2 +- src/current/v23.2/eventlog.md | 2 +- src/current/v23.2/functions-and-operators.md | 8 +- src/current/v23.2/log-formats.md | 2 +- src/current/v23.2/logging.md | 2 +- src/current/v24.1/cluster-settings.md | 2 +- src/current/v24.1/eventlog.md | 2 +- src/current/v24.1/functions-and-operators.md | 8 +- src/current/v24.1/log-formats.md | 2 +- src/current/v24.1/logging.md | 2 +- src/current/v24.2/cluster-settings.md | 2 +- src/current/v24.2/eventlog.md | 2 +- src/current/v24.2/functions-and-operators.md | 8 +- src/current/v24.2/log-formats.md | 2 +- src/current/v24.2/logging.md | 2 +- src/current/v24.3/cluster-settings.md | 2 +- src/current/v24.3/eventlog.md | 2 +- src/current/v24.3/functions-and-operators.md | 8 +- src/current/v24.3/log-formats.md | 2 +- src/current/v24.3/logging.md | 2 +- src/current/v25.1/cluster-settings.md | 2 +- src/current/v25.1/eventlog.md | 2 +- src/current/v25.1/functions-and-operators.md | 8 +- src/current/v25.1/log-formats.md | 2 +- src/current/v25.1/logging.md | 2 +- src/current/v25.2/cluster-settings.md | 2 +- src/current/v25.2/eventlog.md | 2 +- src/current/v25.2/functions-and-operators.md | 8 +- src/current/v25.2/log-formats.md | 2 +- src/current/v25.2/logging.md | 2 +- src/current/v25.3/cluster-settings.md | 2 +- src/current/v25.3/eventlog.md | 2 +- src/current/v25.3/functions-and-operators.md | 8 +- src/current/v25.3/log-formats.md | 2 +- src/current/v25.3/logging.md | 2 +- src/current/v25.4/cluster-settings.md | 2 +- src/current/v25.4/eventlog.md | 2 +- src/current/v25.4/functions-and-operators.md | 8 +- src/current/v25.4/log-formats.md | 2 +- src/current/v25.4/logging.md | 2 +- src/current/v26.1/cluster-settings.md | 2 +- src/current/v26.1/eventlog.md | 2 +- src/current/v26.1/functions-and-operators.md | 8 +- src/current/v26.1/log-formats.md | 2 +- src/current/v26.1/logging.md | 2 +- src/current/v26.2/cluster-settings.md | 2 +- src/current/v26.2/eventlog.md | 2 +- src/current/v26.2/functions-and-operators.md | 8 +- src/current/v26.2/log-formats.md | 2 +- src/current/v26.2/logging.md | 2 +- 143 files changed, 106707 insertions(+), 88 deletions(-) create mode 100644 src/current/_includes/cockroach-generated/release-23.1/eventlog.md create mode 100644 src/current/_includes/cockroach-generated/release-23.1/logformats.md create mode 100644 src/current/_includes/cockroach-generated/release-23.1/logging.md create mode 100644 src/current/_includes/cockroach-generated/release-23.1/settings/settings.html create mode 100644 src/current/_includes/cockroach-generated/release-23.1/sql/aggregates.md create mode 100644 src/current/_includes/cockroach-generated/release-23.1/sql/functions.md create mode 100644 src/current/_includes/cockroach-generated/release-23.1/sql/operators.md create mode 100644 src/current/_includes/cockroach-generated/release-23.1/sql/window_functions.md create mode 100644 src/current/_includes/cockroach-generated/release-23.2/eventlog.md create mode 100644 src/current/_includes/cockroach-generated/release-23.2/logformats.md create mode 100644 src/current/_includes/cockroach-generated/release-23.2/logging.md create mode 100644 src/current/_includes/cockroach-generated/release-23.2/settings/settings.html create mode 100644 src/current/_includes/cockroach-generated/release-23.2/sql/aggregates.md create mode 100644 src/current/_includes/cockroach-generated/release-23.2/sql/functions.md create mode 100644 src/current/_includes/cockroach-generated/release-23.2/sql/operators.md create mode 100644 src/current/_includes/cockroach-generated/release-23.2/sql/window_functions.md create mode 100644 src/current/_includes/cockroach-generated/release-24.1/eventlog.md create mode 100644 src/current/_includes/cockroach-generated/release-24.1/logformats.md create mode 100644 src/current/_includes/cockroach-generated/release-24.1/logging.md create mode 100644 src/current/_includes/cockroach-generated/release-24.1/settings/settings.html create mode 100644 src/current/_includes/cockroach-generated/release-24.1/sql/aggregates.md create mode 100644 src/current/_includes/cockroach-generated/release-24.1/sql/functions.md create mode 100644 src/current/_includes/cockroach-generated/release-24.1/sql/operators.md create mode 100644 src/current/_includes/cockroach-generated/release-24.1/sql/window_functions.md create mode 100644 src/current/_includes/cockroach-generated/release-24.2/eventlog.md create mode 100644 src/current/_includes/cockroach-generated/release-24.2/logformats.md create mode 100644 src/current/_includes/cockroach-generated/release-24.2/logging.md create mode 100644 src/current/_includes/cockroach-generated/release-24.2/settings/settings.html create mode 100644 src/current/_includes/cockroach-generated/release-24.2/sql/aggregates.md create mode 100644 src/current/_includes/cockroach-generated/release-24.2/sql/functions.md create mode 100644 src/current/_includes/cockroach-generated/release-24.2/sql/operators.md create mode 100644 src/current/_includes/cockroach-generated/release-24.2/sql/window_functions.md create mode 100644 src/current/_includes/cockroach-generated/release-24.3/eventlog.md create mode 100644 src/current/_includes/cockroach-generated/release-24.3/logformats.md create mode 100644 src/current/_includes/cockroach-generated/release-24.3/logging.md create mode 100644 src/current/_includes/cockroach-generated/release-24.3/settings/settings.html create mode 100644 src/current/_includes/cockroach-generated/release-24.3/sql/aggregates.md create mode 100644 src/current/_includes/cockroach-generated/release-24.3/sql/functions.md create mode 100644 src/current/_includes/cockroach-generated/release-24.3/sql/operators.md create mode 100644 src/current/_includes/cockroach-generated/release-24.3/sql/window_functions.md create mode 100644 src/current/_includes/cockroach-generated/release-25.1/eventlog.md create mode 100644 src/current/_includes/cockroach-generated/release-25.1/logformats.md create mode 100644 src/current/_includes/cockroach-generated/release-25.1/logging.md create mode 100644 src/current/_includes/cockroach-generated/release-25.1/settings/settings.html create mode 100644 src/current/_includes/cockroach-generated/release-25.1/sql/aggregates.md create mode 100644 src/current/_includes/cockroach-generated/release-25.1/sql/functions.md create mode 100644 src/current/_includes/cockroach-generated/release-25.1/sql/operators.md create mode 100644 src/current/_includes/cockroach-generated/release-25.1/sql/window_functions.md create mode 100644 src/current/_includes/cockroach-generated/release-25.2/eventlog.md create mode 100644 src/current/_includes/cockroach-generated/release-25.2/logformats.md create mode 100644 src/current/_includes/cockroach-generated/release-25.2/logging.md create mode 100644 src/current/_includes/cockroach-generated/release-25.2/settings/settings.html create mode 100644 src/current/_includes/cockroach-generated/release-25.2/sql/aggregates.md create mode 100644 src/current/_includes/cockroach-generated/release-25.2/sql/functions.md create mode 100644 src/current/_includes/cockroach-generated/release-25.2/sql/operators.md create mode 100644 src/current/_includes/cockroach-generated/release-25.2/sql/window_functions.md create mode 100644 src/current/_includes/cockroach-generated/release-25.3/eventlog.md create mode 100644 src/current/_includes/cockroach-generated/release-25.3/logformats.md create mode 100644 src/current/_includes/cockroach-generated/release-25.3/logging.md create mode 100644 src/current/_includes/cockroach-generated/release-25.3/settings/settings.html create mode 100644 src/current/_includes/cockroach-generated/release-25.3/sql/aggregates.md create mode 100644 src/current/_includes/cockroach-generated/release-25.3/sql/functions.md create mode 100644 src/current/_includes/cockroach-generated/release-25.3/sql/operators.md create mode 100644 src/current/_includes/cockroach-generated/release-25.3/sql/window_functions.md create mode 100644 src/current/_includes/cockroach-generated/release-25.4/eventlog.md create mode 100644 src/current/_includes/cockroach-generated/release-25.4/logformats.md create mode 100644 src/current/_includes/cockroach-generated/release-25.4/logging.md create mode 100644 src/current/_includes/cockroach-generated/release-25.4/settings/settings.html create mode 100644 src/current/_includes/cockroach-generated/release-25.4/sql/aggregates.md create mode 100644 src/current/_includes/cockroach-generated/release-25.4/sql/functions.md create mode 100644 src/current/_includes/cockroach-generated/release-25.4/sql/operators.md create mode 100644 src/current/_includes/cockroach-generated/release-25.4/sql/window_functions.md create mode 100644 src/current/_includes/cockroach-generated/release-26.1/eventlog.md create mode 100644 src/current/_includes/cockroach-generated/release-26.1/logformats.md create mode 100644 src/current/_includes/cockroach-generated/release-26.1/logging.md create mode 100644 src/current/_includes/cockroach-generated/release-26.1/settings/settings.html create mode 100644 src/current/_includes/cockroach-generated/release-26.1/sql/aggregates.md create mode 100644 src/current/_includes/cockroach-generated/release-26.1/sql/functions.md create mode 100644 src/current/_includes/cockroach-generated/release-26.1/sql/operators.md create mode 100644 src/current/_includes/cockroach-generated/release-26.1/sql/window_functions.md create mode 100644 src/current/_includes/cockroach-generated/release-26.2/eventlog.md create mode 100644 src/current/_includes/cockroach-generated/release-26.2/logformats.md create mode 100644 src/current/_includes/cockroach-generated/release-26.2/logging.md create mode 100644 src/current/_includes/cockroach-generated/release-26.2/settings/settings.html create mode 100644 src/current/_includes/cockroach-generated/release-26.2/sql/aggregates.md create mode 100644 src/current/_includes/cockroach-generated/release-26.2/sql/functions.md create mode 100644 src/current/_includes/cockroach-generated/release-26.2/sql/operators.md create mode 100644 src/current/_includes/cockroach-generated/release-26.2/sql/window_functions.md diff --git a/src/current/_includes/cockroach-generated/release-23.1/eventlog.md b/src/current/_includes/cockroach-generated/release-23.1/eventlog.md new file mode 100644 index 00000000000..1c12182df64 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-23.1/eventlog.md @@ -0,0 +1,3216 @@ +Certain notable events are reported using a structured format. +Commonly, these notable events are also copied to the table +`system.eventlog`, unless the cluster setting +`server.eventlog.enabled` is unset. + +Additionally, notable events are copied to specific external logging +channels in log messages, where they can be collected for further processing. + +The sections below document the possible notable event types +in this version of CockroachDB. For each event type, a table +documents the possible fields. A field may be omitted from +an event if its value is empty or zero. + +A field is also considered "Sensitive" if it may contain +application-specific information or personally identifiable information (PII). In that case, +the copy of the event sent to the external logging channel +will contain redaction markers in a format that is compatible +with the redaction facilities in [`cockroach debug zip`](cockroach-debug-zip.html) +and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html), +provided the `redactable` functionality is enabled on the logging sink. + +Events not documented on this page will have an unstructured format in log messages. + +## Cluster-level events + +Events in this category pertain to an entire cluster and are +not relative to any particular tenant. + +In a multi-tenant setup, the `system.eventlog` table for individual +tenants cannot contain a copy of cluster-level events; conversely, +the `system.eventlog` table in the system tenant cannot contain the +SQL-level events for individual tenants. + +Events in this category are logged to the `OPS` channel. + + +### `certs_reload` + +An event of type `certs_reload` is recorded when the TLS certificates are +reloaded/rotated from disk. + + +| Field | Description | Sensitive | +|--|--|--| +| `Success` | Whether the operation completed without errors. | no | +| `ErrorMessage` | If an error was encountered, the text of the error. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `node_decommissioned` + +An event of type `node_decommissioned` is recorded when a node is marked as +decommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_decommissioning` + +An event of type `node_decommissioning` is recorded when a node is marked as +decommissioning. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_join` + +An event of type `node_join` is recorded when a node joins the cluster. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_recommissioned` + +An event of type `node_recommissioned` is recorded when a decommissioning node is +recommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_restart` + +An event of type `node_restart` is recorded when an existing node rejoins the cluster +after being offline. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_connection_timeout` + +An event of type `node_shutdown_connection_timeout` is recorded when SQL connections remain open +during shutdown, after waiting for the server.shutdown.connections.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still open after waiting for the client to close them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.connections.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_transaction_timeout` + +An event of type `node_shutdown_transaction_timeout` is recorded when SQL transactions remain open +during shutdown, after waiting for the server.shutdown.transactions.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still running SQL transactions after waiting for the client to end them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.transactions.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `tenant_shared_service_start` + +An event of type `tenant_shared_service_start` is recorded when a tenant server +is started inside the same process as the KV layer. + + +| Field | Description | Sensitive | +|--|--|--| +| `OK` | Whether the startup was successful. | no | +| `ErrorText` | If the startup failed, the text of the error. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +### `tenant_shared_service_stop` + +An event of type `tenant_shared_service_stop` is recorded when a tenant server +is shut down inside the same process as the KV layer. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +## Debugging events + +Events in this category pertain to debugging operations performed by +operators or (more commonly) Cockroach Labs employees. These operations can +e.g. directly access and mutate internal state, breaking system invariants. + +Events in this category are logged to the `OPS` channel. + + +### `debug_recover_replica` + +An event of type `debug_recover_replica` is recorded when unsafe loss of quorum recovery is performed. + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `StoreID` | | no | +| `SurvivorReplicaID` | | no | +| `UpdatedReplicaID` | | no | +| `StartKey` | | yes | +| `EndKey` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +### `debug_send_kv_batch` + +An event of type `debug_send_kv_batch` is recorded when an arbitrary KV BatchRequest is submitted +to the cluster via the `debug send-kv-batch` CLI command. + + +| Field | Description | Sensitive | +|--|--|--| +| `BatchRequest` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +## Health events + +Events in this category pertain to the health of one or more servers. + +Events in this category are logged to the `HEALTH` channel. + + +### `runtime_stats` + +An event of type `runtime_stats` is recorded every 10 seconds as server health metrics. + + +| Field | Description | Sensitive | +|--|--|--| +| `MemRSSBytes` | The process resident set size. Expressed as bytes. | no | +| `GoroutineCount` | The number of goroutines. | no | +| `MemStackSysBytes` | The stack system memory used. Expressed as bytes. | no | +| `GoAllocBytes` | The memory allocated by Go. Expressed as bytes. | no | +| `GoTotalBytes` | The total memory allocated by Go but not released. Expressed as bytes. | no | +| `GoStatsStaleness` | The staleness of the Go memory statistics. Expressed in seconds. | no | +| `HeapFragmentBytes` | The amount of heap fragmentation. Expressed as bytes. | no | +| `HeapReservedBytes` | The amount of heap reserved. Expressed as bytes. | no | +| `HeapReleasedBytes` | The amount of heap released. Expressed as bytes. | no | +| `CGoAllocBytes` | The memory allocated outside of Go. Expressed as bytes. | no | +| `CGoTotalBytes` | The total memory allocated outside of Go but not released. Expressed as bytes. | no | +| `CGoCallRate` | The total number of calls outside of Go over time. Expressed as operations per second. | no | +| `CPUUserPercent` | The user CPU percentage. | no | +| `CPUSysPercent` | The system CPU percentage. | no | +| `GCPausePercent` | The GC pause percentage. | no | +| `GCRunCount` | The total number of GC runs. | no | +| `NetHostRecvBytes` | The bytes received on all network interfaces since this process started. | no | +| `NetHostSendBytes` | The bytes sent on all network interfaces since this process started. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Job events + +Events in this category pertain to long-running jobs that are orchestrated by +a node's job registry. These system processes can create and/or modify stored +objects during the course of their execution. + +A job might choose to emit multiple events during its execution when +transitioning from one "state" to another. +Egs: IMPORT/RESTORE will emit events on job creation and successful +completion. If the job fails, events will be emitted on job creation, +failure, and successful revert. + +Events in this category are logged to the `OPS` channel. + + +### `import` + +An event of type `import` is recorded when an import job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `restore` + +An event of type `restore` is recorded when a restore job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +## Miscellaneous SQL events + +Events in this category report miscellaneous SQL events. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own system.eventlog table. + +Events in this category are logged to the `DEV` channel. + + +### `set_cluster_setting` + +An event of type `set_cluster_setting` is recorded when a cluster setting is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `set_tenant_cluster_setting` + +An event of type `set_tenant_cluster_setting` is recorded when a cluster setting override +is changed, either for another tenant or for all tenants. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | +| `TenantId` | The target Tenant ID. Empty if targeting all tenants. | no | +| `AllTenants` | Whether the override applies to all tenants. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +## SQL Access Audit Events + +Events in this category are generated when a table has been +marked as audited via `ALTER TABLE ... EXPERIMENTAL_AUDIT SET`. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SENSITIVE_ACCESS` channel. + + +### `admin_query` + +An event of type `admin_query` is recorded when a user with admin privileges (the user +is directly or indirectly a member of the admin role) executes a query. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `role_based_audit_event` + +An event of type `role_based_audit_event` is an audit event recorded when an executed query belongs to a user whose role +membership(s) correspond to any role that is enabled to emit an audit log via the sql.log.user_audit +cluster setting. + + +| Field | Description | Sensitive | +|--|--|--| +| `Role` | The configured audit role that emitted this log. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sensitive_table_access` + +An event of type `sensitive_table_access` is recorded when an access is performed to +a table marked as audited. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table being audited. | yes | +| `AccessMode` | How the table was accessed (r=read / rw=read/write). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +## SQL Execution Log + +Events in this category report executed queries. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `query_execute` + +An event of type `query_execute` is recorded when a query is executed, +and the cluster setting `sql.trace.log_statement_execute` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +## SQL Logical Schema Changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the SQL logical +schema. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SQL_SCHEMA` channel. + + +### `alter_database_add_region` + +An event of type `alter_database_add_region` is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | yes | +| `RegionName` | The region being added. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_drop_region` + +AlterDatabaseAddRegion is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | yes | +| `RegionName` | The region being dropped. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_placement` + +An event of type `alter_database_placement` is recorded when the database placement is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | yes | +| `Placement` | The new placement policy. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_primary_region` + +An event of type `alter_database_primary_region` is recorded when a primary region is added/modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | yes | +| `PrimaryRegionName` | The new primary region. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_set_zone_config_extension` + +An event of type `alter_database_set_zone_config_extension` is recorded when a zone config extension is changed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `alter_database_survival_goal` + +An event of type `alter_database_survival_goal` is recorded when the survival goal is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | yes | +| `SurvivalGoal` | The new survival goal | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_function_options` + +An event of type `alter_function_options` is recorded when a user-defined function's options are +altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the affected function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_index` + +An event of type `alter_index` is recorded when an index is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | yes | +| `IndexName` | The name of the affected index. | yes | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_index_visible` + +AlterIndex is recorded when an index visibility is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | yes | +| `IndexName` | The name of the affected index. | yes | +| `NotVisible` | Set true if index is not visible. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_sequence` + +An event of type `alter_sequence` is recorded when a sequence is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_table` + +An event of type `alter_table` is recorded when a table is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update, if any. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_type` + +EventAlterType is recorded when a user-defined type is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_column` + +An event of type `comment_on_column` is recorded when a column is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected column. | yes | +| `ColumnName` | The affected column. | yes | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_constraint` + +An event of type `comment_on_constraint` is recorded when an constraint is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected constraint. | yes | +| `ConstraintName` | The name of the affected constraint. | yes | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_database` + +CommentOnTable is recorded when a database is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_index` + +An event of type `comment_on_index` is recorded when an index is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | yes | +| `IndexName` | The name of the affected index. | yes | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_schema` + + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | Name of the affected schema. | yes | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_table` + +An event of type `comment_on_table` is recorded when a table is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `convert_to_schema` + +An event of type `convert_to_schema` is recorded when a database is converted to a schema. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database being converted to a schema. | yes | +| `NewDatabaseParent` | The name of the parent database for the new schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_database` + +An event of type `create_database` is recorded when a database is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the new database. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_function` + +An event of type `create_function` is recorded when a user-defined function is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the created function. | yes | +| `IsReplace` | If the new function is a replace of an existing function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_index` + +An event of type `create_index` is recorded when an index is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the new index. | yes | +| `IndexName` | The name of the new index. | yes | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_schema` + +An event of type `create_schema` is recorded when a schema is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the new schema. | yes | +| `Owner` | The name of the owner for the new schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_sequence` + +An event of type `create_sequence` is recorded when a sequence is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the new sequence. | yes | +| `Owner` | The name of the owner for the new sequence. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_statistics` + +An event of type `create_statistics` is recorded when statistics are collected for a +table. + +Events of this type are only collected when the cluster setting +`sql.stats.post_events.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table for which the statistics were created. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_table` + +An event of type `create_table` is recorded when a table is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the new table. | yes | +| `Owner` | The name of the owner for the new table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_type` + +An event of type `create_type` is recorded when a user-defined type is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the new type. | yes | +| `Owner` | The name of the owner for the new type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_view` + +An event of type `create_view` is recorded when a view is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the new view. | yes | +| `Owner` | The name of the owner of the new view. | yes | +| `ViewQuery` | The SQL selection clause used to define the view. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_database` + +An event of type `drop_database` is recorded when a database is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | +| `DroppedSchemaObjects` | The names of the schemas dropped by a cascade operation. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_function` + +An event of type `drop_function` is recorded when a user-defined function is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the created function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_index` + +An event of type `drop_index` is recorded when an index is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | yes | +| `IndexName` | The name of the affected index. | yes | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_schema` + +An event of type `drop_schema` is recorded when a schema is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_sequence` + +An event of type `drop_sequence` is recorded when a sequence is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_table` + +An event of type `drop_table` is recorded when a table is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_type` + +An event of type `drop_type` is recorded when a user-defined type is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_view` + +An event of type `drop_view` is recorded when a view is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the affected view. | yes | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `finish_schema_change` + +An event of type `finish_schema_change` is recorded when a previously initiated schema +change has completed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `finish_schema_change_rollback` + +An event of type `finish_schema_change_rollback` is recorded when a previously +initiated schema change rollback has completed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `force_delete_table_data_entry` + + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_database` + +An event of type `rename_database` is recorded when a database is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The old name of the affected database. | yes | +| `NewDatabaseName` | The new name of the affected database. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_function` + +An event of type `rename_function` is recorded when a user-defined function is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The old name of the affected function. | yes | +| `NewFunctionName` | The new name of the affected function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_schema` + +An event of type `rename_schema` is recorded when a schema is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The old name of the affected schema. | yes | +| `NewSchemaName` | The new name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_table` + +An event of type `rename_table` is recorded when a table, sequence or view is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The old name of the affected table. | yes | +| `NewTableName` | The new name of the affected table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_type` + +An event of type `rename_type` is recorded when a user-defined type is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The old name of the affected type. | yes | +| `NewTypeName` | The new name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `reverse_schema_change` + +An event of type `reverse_schema_change` is recorded when an in-progress schema change +encounters a problem and is reversed. + + +| Field | Description | Sensitive | +|--|--|--| +| `Error` | The error encountered that caused the schema change to be reversed. The specific format of the error is variable and can change across releases without warning. | yes | +| `SQLSTATE` | The SQLSTATE code for the error. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `set_schema` + +An event of type `set_schema` is recorded when a table, view, sequence or type's schema is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorName` | The old name of the affected descriptor. | yes | +| `NewDescriptorName` | The new name of the affected descriptor. | yes | +| `DescriptorType` | The descriptor type being changed (table, view, sequence, type). | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `truncate_table` + +An event of type `truncate_table` is recorded when a table is truncated. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_delete_descriptor` + +An event of type `unsafe_delete_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_delete_descriptor(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | yes | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_delete_namespace_entry` + +An event of type `unsafe_delete_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_delete_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | yes | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_upsert_descriptor` + +An event of type `unsafe_upsert_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_upsert_descriptor(). + + +| Field | Description | Sensitive | +|--|--|--| +| `PreviousDescriptor` | | yes | +| `NewDescriptor` | | yes | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_upsert_namespace_entry` + +An event of type `unsafe_upsert_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_upsert_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | yes | +| `PreviousID` | | no | +| `Force` | | no | +| `FailedValidation` | | no | +| `ValidationErrors` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +## SQL Privilege changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the privilege +grants for stored objects. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `PRIVILEGES` channel. + + +### `alter_database_owner` + +An event of type `alter_database_owner` is recorded when a database's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database being affected. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_default_privileges` + +An event of type `alter_default_privileges` is recorded when default privileges are changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | +| `RoleName` | Either role_name should be populated or for_all_roles should be true. The role having its default privileges altered. | yes | +| `ForAllRoles` | Identifies if FOR ALL ROLES is used. | no | +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `alter_function_owner` + +AlterTableOwner is recorded when the owner of a user-defined function is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The name of the affected user-defined function. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_schema_owner` + +An event of type `alter_schema_owner` is recorded when a schema's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_table_owner` + +An event of type `alter_table_owner` is recorded when the owner of a table, view or sequence is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected object. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_type_owner` + +An event of type `alter_type_owner` is recorded when the owner of a user-defiend type is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `change_database_privilege` + +An event of type `change_database_privilege` is recorded when privileges are +added to / removed from a user for a database object. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_function_privilege` + + + +| Field | Description | Sensitive | +|--|--|--| +| `FuncName` | The name of the affected function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_schema_privilege` + +An event of type `change_schema_privilege` is recorded when privileges are added to / +removed from a user for a schema object. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_table_privilege` + +An event of type `change_table_privilege` is recorded when privileges are added to / removed +from a user for a table, sequence or view object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_type_privilege` + +An event of type `change_type_privilege` is recorded when privileges are added to / +removed from a user for a type object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +## SQL Session events + +Events in this category report SQL client connections +and sessions. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SESSIONS` channel. + + +### `client_authentication_failed` + +An event of type `client_authentication_failed` is reported when a client session +did not authenticate successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Reason` | The reason for the authentication failure. See below for possible values for type `AuthFailReason`. | no | +| `Detail` | The detailed error for the authentication failure. | partially | +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_info` + +An event of type `client_authentication_info` is reported for intermediate +steps during the authentication process. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used, once known. | no | +| `Info` | The authentication progress message. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_ok` + +An event of type `client_authentication_ok` is reported when a client session +was authenticated successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_connection_end` + +An event of type `client_connection_end` is reported when a client connection +is closed. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_connection_start` + +An event of type `client_connection_start` is reported when a client connection +is established. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_session_end` + +An event of type `client_session_end` is reported when a client session +is completed. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +## SQL Slow Query Log + +Events in this category report slow query execution. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_PERF` channel. + + +### `large_row` + +An event of type `large_row` is recorded when a statement tries to write a row larger than +cluster setting `sql.guardrails.max_row_size_log` to the database. Multiple +LargeRow events will be recorded for statements writing multiple large rows. +LargeRow events are recorded before the transaction commits, so in the case +of transaction abort there will not be a corresponding row in the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query` + +An event of type `slow_query` is recorded when a query triggers the "slow query" condition. + +As of this writing, the condition requires: +- the cluster setting `sql.log.slow_query.latency_threshold` +set to a non-zero value, AND +- EITHER of the following conditions: +- the actual age of the query exceeds the configured threshold; AND/OR +- the query performs a full table/index scan AND the cluster setting +`sql.log.slow_query.experimental_full_table_scans.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit` + +An event of type `txn_rows_read_limit` is recorded when a transaction tries to read more rows than +cluster setting `sql.defaults.transaction_rows_read_log`. There will only be +a single record for a single transaction (unless it is retried) even if there +are more statement within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit` + +An event of type `txn_rows_written_limit` is recorded when a transaction tries to write more rows +than cluster setting `sql.defaults.transaction_rows_written_log`. There will +only be a single record for a single transaction (unless it is retried) even +if there are more mutation statements within the transaction that haven't +been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL Slow Query Log (Internal) + +Events in this category report slow query execution by +internal executors, i.e., when CockroachDB internally issues +SQL statements. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_INTERNAL_PERF` channel. + + +### `large_row_internal` + +An event of type `large_row_internal` is recorded when an internal query tries to write a row +larger than cluster settings `sql.guardrails.max_row_size_log` or +`sql.guardrails.max_row_size_err` to the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query_internal` + +An event of type `slow_query_internal` is recorded when a query triggers the "slow query" condition, +and the cluster setting `sql.log.slow_query.internal_queries.enabled` is +set. +See the documentation for the event type `slow_query` for details about +the "slow query" condition. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit_internal` + +An event of type `txn_rows_read_limit_internal` is recorded when an internal transaction tries to +read more rows than cluster setting `sql.defaults.transaction_rows_read_log` +or `sql.defaults.transaction_rows_read_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit_internal` + +An event of type `txn_rows_written_limit_internal` is recorded when an internal transaction tries to +write more rows than cluster setting +`sql.defaults.transaction_rows_written_log` or +`sql.defaults.transaction_rows_written_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL User and Role operations + +Events in this category pertain to SQL statements that modify the +properties of users and roles. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `USER_ADMIN` channel. + + +### `alter_role` + +An event of type `alter_role` is recorded when a role is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | +| `Options` | The options set on the user/role. | no | +| `SetInfo` | Information corresponding to an ALTER ROLE SET statement. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_role` + +An event of type `create_role` is recorded when a role is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the new user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_role` + +An event of type `drop_role` is recorded when a role is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `grant_role` + +An event of type `grant_role` is recorded when a role is granted. + + +| Field | Description | Sensitive | +|--|--|--| +| `GranteeRoles` | The roles being granted to. | yes | +| `Members` | The roles being granted. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `password_hash_converted` + +An event of type `password_hash_converted` is recorded when the password credentials +are automatically converted server-side. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the user/role whose credentials have been converted. | yes | +| `OldMethod` | The previous hash method. | no | +| `NewMethod` | The new hash method. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Storage telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `level_stats` + +An event of type `level_stats` contains per-level statistics for an LSM. + + +| Field | Description | Sensitive | +|--|--|--| +| `Level` | level is the level ID in a LSM (e.g. level(L0) == 0, etc.) | no | +| `NumFiles` | num_files is the number of files in the level (gauge). | no | +| `SizeBytes` | size_bytes is the size of the level, in bytes (gauge). | no | +| `Score` | score is the compaction score of the level (gauge). | no | +| `BytesIn` | bytes_in is the number of bytes written to this level (counter). | no | +| `BytesIngested` | bytes_ingested is the number of bytes ingested into this level (counter). | no | +| `BytesMoved` | bytes_moved is the number of bytes moved into this level via a move-compaction (counter). | no | +| `BytesRead` | bytes_read is the number of bytes read from this level, during compactions (counter). | no | +| `BytesCompacted` | bytes_compacted is the number of bytes written to this level during compactions (counter). | no | +| `BytesFlushed` | bytes flushed is the number of bytes flushed to this level. This value is always zero for levels other than L0 (counter). | no | +| `TablesCompacted` | tables_compacted is the count of tables compacted into this level (counter). | no | +| `TablesFlushed` | tables_flushed is the count of tables flushed into this level (counter). | no | +| `TablesIngested` | tables_ingested is the count of tables ingested into this level (counter). | no | +| `TablesMoved` | tables_moved is the count of tables moved into this level via move-compactions (counter). | no | +| `NumSublevels` | num_sublevel is the count of sublevels for the level. This value is always zero for levels other than L0 (gauge). | no | + + + +### `store_stats` + +An event of type `store_stats` contains per store stats. + +Note that because stats are scoped to the lifetime of the process, counters +(and certain gauges) will be reset across node restarts. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeId` | node_id is the ID of the node. | no | +| `StoreId` | store_id is the ID of the store. | no | +| `Levels` | levels is a nested message containing per-level statistics. | yes | +| `CacheSize` | cache_size is the size of the cache for the store, in bytes (gauge). | no | +| `CacheCount` | cache_count is the number of items in the cache (gauge). | no | +| `CacheHits` | cache_hits is the number of cache hits (counter). | no | +| `CacheMisses` | cache_misses is the number of cache misses (counter). | no | +| `CompactionCountDefault` | compaction_count_default is the count of default compactions (counter). | no | +| `CompactionCountDeleteOnly` | compaction_count_delete_only is the count of delete-only compactions (counter). | no | +| `CompactionCountElisionOnly` | compaction_count_elision_only is the count of elision-only compactions (counter). | no | +| `CompactionCountMove` | compaction_count_move is the count of move-compactions (counter). | no | +| `CompactionCountRead` | compaction_count_read is the count of read-compactions (counter). | no | +| `CompactionCountRewrite` | compaction_count_rewrite is the count of rewrite-compactions (counter). | no | +| `CompactionNumInProgress` | compactions_num_in_progress is the number of compactions in progress (gauge). | no | +| `CompactionMarkedFiles` | compaction_marked_files is the count of files marked for compaction (gauge). | no | +| `FlushCount` | flush_count is the number of flushes (counter). | no | +| `FlushIngestCount` | | no | +| `FlushIngestTableCount` | | no | +| `FlushIngestTableBytes` | | no | +| `MemtableSize` | memtable_size is the total size allocated to all memtables and (large) batches, in bytes (gauge). | no | +| `MemtableCount` | memtable_count is the count of memtables (gauge). | no | +| `MemtableZombieCount` | memtable_zombie_count is the count of memtables no longer referenced by the current DB state, but still in use by an iterator (gauge). | no | +| `MemtableZombieSize` | memtable_zombie_size is the size, in bytes, of all zombie memtables (gauge). | no | +| `WalLiveCount` | wal_live_count is the count of live WAL files (gauge). | no | +| `WalLiveSize` | wal_live_size is the size, in bytes, of live data in WAL files. With WAL recycling, this value is less than the actual on-disk size of the WAL files (gauge). | no | +| `WalObsoleteCount` | wal_obsolete_count is the count of obsolete WAL files (gauge). | no | +| `WalObsoleteSize` | wal_obsolete_size is the size of obsolete WAL files, in bytes (gauge). | no | +| `WalPhysicalSize` | wal_physical_size is the size, in bytes, of the WAL files on disk (gauge). | no | +| `WalBytesIn` | wal_bytes_in is the number of logical bytes written to the WAL (counter). | no | +| `WalBytesWritten` | wal_bytes_written is the number of bytes written to the WAL (counter). | no | +| `TableObsoleteCount` | table_obsolete_count is the number of tables which are no longer referenced by the current DB state or any open iterators (gauge). | no | +| `TableObsoleteSize` | table_obsolete_size is the size, in bytes, of obsolete tables (gauge). | no | +| `TableZombieCount` | table_zombie_count is the number of tables no longer referenced by the current DB state, but are still in use by an open iterator (gauge). | no | +| `TableZombieSize` | table_zombie_size is the size, in bytes, of zombie tables (gauge). | no | +| `RangeKeySetsCount` | range_key_sets_count is the approximate count of internal range key sets in the store. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `captured_index_usage_stats` + +An event of type `captured_index_usage_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `TotalReadCount` | TotalReadCount is the number of times the index has been read. | no | +| `LastRead` | LastRead is the timestamp at which the index was last read. | no | +| `TableID` | TableID is the ID of the table on which the index was created. This is same as descpb.TableID and is unique within the cluster. | no | +| `IndexID` | IndexID is the ID of the index within the scope of the given table. | no | +| `DatabaseName` | DatabaseName is the name of the database in which the index was created. | no | +| `TableName` | TableName is the name of the table on which the index was created. | no | +| `IndexName` | IndexName is the name of the index within the scope of the given table. | no | +| `IndexType` | IndexType is the type of the index. Index types include "primary" and "secondary". | no | +| `IsUnique` | IsUnique indicates if the index has a UNIQUE constraint. | no | +| `IsInverted` | IsInverted indicates if the index is an inverted index. | no | +| `CreatedAt` | CreatedAt is the timestamp at which the index was created. | no | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `changefeed_emitted_bytes` + +An event of type `changefeed_emitted_bytes` is an event representing the bytes emitted by a changefeed over an interval. + + +| Field | Description | Sensitive | +|--|--|--| +| `JobId` | The job id for enterprise changefeeds. | no | +| `EmittedBytes` | The number of bytes emitted. | no | +| `LoggingInterval` | The time period in nanoseconds between emitting telemetry events of this type (per-aggregator). | no | +| `Closing` | Flag to indicate that the changefeed is closing. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | + +### `changefeed_failed` + +An event of type `changefeed_failed` is an event for any Changefeed failure since the plan hook +was triggered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FailureType` | The reason / environment with which the changefeed failed (ex: connection_closed, changefeed_behind) | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | + +### `create_changefeed` + +An event of type `create_changefeed` is an event for any CREATE CHANGEFEED query that +successfully starts running. Failed CREATE statements will show up as +ChangefeedFailed events. + + +| Field | Description | Sensitive | +|--|--|--| +| `Transformation` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | + +### `hot_ranges_stats` + +An event of type `hot_ranges_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `Qps` | | no | +| `DatabaseName` | DatabaseName is the name of the database in which the index was created. | yes | +| `TableName` | TableName is the name of the table on which the index was created. | yes | +| `IndexName` | IndexName is the name of the index within the scope of the given table. | yes | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | yes | +| `LeaseholderNodeID` | LeaseholderNodeID indicates the Node ID that is the current leaseholder for the given range. | no | +| `WritesPerSecond` | Writes per second is the recent number of keys written per second on this range. | no | +| `ReadsPerSecond` | Reads per second is the recent number of keys read per second on this range. | no | +| `WriteBytesPerSecond` | Write bytes per second is the recent number of bytes written per second on this range. | no | +| `ReadBytesPerSecond` | Read bytes per second is the recent number of bytes read per second on this range. | no | +| `CPUTimePerSecond` | CPU time per second is the recent cpu usage in nanoseconds of this range. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `recovery_event` + +An event of type `recovery_event` is an event that is logged on every invocation of BACKUP, +RESTORE, and on every BACKUP schedule creation, with the appropriate subset +of fields populated depending on the type of event. This event is is also +logged whenever a BACKUP and RESTORE job completes or fails. + + +| Field | Description | Sensitive | +|--|--|--| +| `RecoveryType` | RecoveryType is the type of recovery described by this event, which is one of - backup - scheduled_backup - create_schedule - restore

It can also be a job event corresponding to the recovery, which is one of - backup_job - scheduled_backup_job - restore_job | no | +| `TargetScope` | TargetScope is the largest scope of the targets that the user is backing up or restoring based on the following order: table < schema < database < full cluster. | no | +| `IsMultiregionTarget` | IsMultiregionTarget is true if any of the targets contain objects with multi-region primitives. | no | +| `TargetCount` | TargetCount is the number of targets the in the BACKUP/RESTORE. | no | +| `DestinationSubdirType` | DestinationSubdirType is - latest: if using the latest subdir - standard: if using a date-based subdir - custom: if using a custom subdir that's not date-based | no | +| `DestinationStorageTypes` | DestinationStorageTypes are the types of storage that the user is backing up to or restoring from. | no | +| `DestinationAuthTypes` | DestinationAuthTypes are the types of authentication methods that the user is using to access the destination storage. | no | +| `IsLocalityAware` | IsLocalityAware indicates if the BACKUP or RESTORE is locality aware. | no | +| `AsOfInterval` | AsOfInterval is the time interval in nanoseconds between the statement timestamp and the timestamp resolved by the AS OF SYSTEM TIME expression. The interval is expressed in nanoseconds. | no | +| `WithRevisionHistory` | WithRevisionHistory is true if the BACKUP includes revision history. | no | +| `HasEncryptionPassphrase` | HasEncryptionPassphrase is true if the user provided an encryption passphrase to encrypt/decrypt their backup. | no | +| `KMSType` | KMSType is the type of KMS the user is using to encrypt/decrypt their backup. | no | +| `KMSCount` | KMSCount is the number of KMS the user is using. | no | +| `Options` | Options contain all the names of the options specified by the user in the BACKUP or RESTORE statement. For options that are accompanied by a value, only those with non-empty values will be present.

It's important to note that there are no option values anywhere in the event payload. Future changes to telemetry should refrain from adding values to the payload unless they are properly redacted. | no | +| `DebugPauseOn` | DebugPauseOn is the type of event that the restore should pause on for debugging purposes. Currently only "error" is supported. | no | +| `JobID` | JobID is the ID of the BACKUP/RESTORE job. | no | +| `ResultStatus` | ResultStatus indicates whether the job succeeded or failed. | no | +| `ErrorText` | ErrorText is the text of the error that caused the job to fail. | partially | +| `RecurringCron` | RecurringCron is the crontab for the incremental backup. | no | +| `FullBackupCron` | FullBackupCron is the crontab for the full backup. | no | +| `CustomFirstRunTime` | CustomFirstRunTime is the timestamp for the user configured first run time. Expressed as nanoseconds since the Unix epoch. | no | +| `OnExecutionFailure` | OnExecutionFailure describes the desired behavior if the schedule fails to execute. | no | +| `OnPreviousRunning` | OnPreviousRunning describes the desired behavior if the previously scheduled BACKUP is still running. | no | +| `IgnoreExistingBackup` | IgnoreExistingBackup is true iff the BACKUP schedule should still be created even if a backup is already present in its destination. | no | +| `ApplicationName` | The application name for the session where recovery event was created. | no | +| `NumRows` | NumRows is the number of rows successfully imported, backed up or restored. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `sampled_query` + +An event of type `sampled_query` is the SQL query event logged to the telemetry channel. It +contains common SQL event/execution details. + + +| Field | Description | Sensitive | +|--|--|--| +| `SkippedQueries` | skipped_queries indicate how many SQL statements were not considered for sampling prior to this one. If the field is omitted, or its value is zero, this indicates that no statement was omitted since the last event. | no | +| `CostEstimate` | Cost of the query as estimated by the optimizer. | no | +| `Distribution` | The distribution of the DistSQL query plan (local, full, or partial). | no | +| `PlanGist` | The query's plan gist bytes as a base64 encoded string. | no | +| `SessionID` | SessionID is the ID of the session that initiated the query. | no | +| `Database` | Name of the database that initiated the query. | no | +| `StatementID` | Statement ID of the query. | no | +| `TransactionID` | Transaction ID of the query. | no | +| `StatementFingerprintID` | Statement fingerprint ID of the query. | no | +| `MaxFullScanRowsEstimate` | Maximum number of rows scanned by a full scan, as estimated by the optimizer. | no | +| `TotalScanRowsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer. | no | +| `OutputRowsEstimate` | The number of rows output by the query, as estimated by the optimizer. | no | +| `StatsAvailable` | Whether table statistics were available to the optimizer when planning the query. | no | +| `NanosSinceStatsCollected` | The maximum number of nanoseconds that have passed since stats were collected on any table scanned by this query. | no | +| `BytesRead` | The number of bytes read from disk. | no | +| `RowsRead` | The number of rows read from disk. | no | +| `RowsWritten` | The number of rows written. | no | +| `InnerJoinCount` | The number of inner joins in the query plan. | no | +| `LeftOuterJoinCount` | The number of left (or right) outer joins in the query plan. | no | +| `FullOuterJoinCount` | The number of full outer joins in the query plan. | no | +| `SemiJoinCount` | The number of semi joins in the query plan. | no | +| `AntiJoinCount` | The number of anti joins in the query plan. | no | +| `IntersectAllJoinCount` | The number of intersect all joins in the query plan. | no | +| `ExceptAllJoinCount` | The number of except all joins in the query plan. | no | +| `HashJoinCount` | The number of hash joins in the query plan. | no | +| `CrossJoinCount` | The number of cross joins in the query plan. | no | +| `IndexJoinCount` | The number of index joins in the query plan. | no | +| `LookupJoinCount` | The number of lookup joins in the query plan. | no | +| `MergeJoinCount` | The number of merge joins in the query plan. | no | +| `InvertedJoinCount` | The number of inverted joins in the query plan. | no | +| `ApplyJoinCount` | The number of apply joins in the query plan. | no | +| `ZigZagJoinCount` | The number of zig zag joins in the query plan. | no | +| `ContentionNanos` | The duration of time in nanoseconds that the query experienced contention. | no | +| `Regions` | The regions of the nodes where SQL processors ran. | no | +| `NetworkBytesSent` | The number of network bytes sent by nodes for this query. | no | +| `MaxMemUsage` | The maximum amount of memory usage by nodes for this query. | no | +| `MaxDiskUsage` | The maximum amount of disk usage by nodes for this query. | no | +| `KVBytesRead` | The number of bytes read at the KV layer for this query. | no | +| `KVRowsRead` | The number of rows read at the KV layer for this query. | no | +| `NetworkMessages` | The number of network messages sent by nodes for this query. | no | +| `IndexRecommendations` | Generated index recommendations for this query. | no | +| `ScanCount` | The number of scans in the query plan. | no | +| `ScanWithStatsCount` | The number of scans using statistics (including forecasted statistics) in the query plan. | no | +| `ScanWithStatsForecastCount` | The number of scans using forecasted statistics in the query plan. | no | +| `TotalScanRowsWithoutForecastsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer without using forecasts. | no | +| `NanosSinceStatsForecasted` | The greatest quantity of nanoseconds that have passed since the forecast time (or until the forecast time, if it is in the future, in which case it will be negative) for any table with forecasted stats scanned by this query. | no | +| `Indexes` | The list of indexes used by this query. | no | +| `CpuTimeNanos` | Collects the cumulative CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `KvGrpcCalls` | The number of grpc calls done to get data form KV nodes | no | +| `KvTimeNanos` | Cumulated time spent waiting for a KV request. This includes disk IO time and potentially network time (if any of the keys are not local). | no | +| `ServiceLatencyNanos` | The time to service the query, from start of parse to end of execute. | no | +| `OverheadLatencyNanos` | The difference between service latency and the sum of parse latency + plan latency + run latency . | no | +| `RunLatencyNanos` | The time to run the query and fetch or compute the result rows. | no | +| `PlanLatencyNanos` | The time to transform the AST into a logical query plan. | no | +| `IdleLatencyNanos` | The time between statement executions in a transaction | no | +| `ParseLatencyNanos` | The time to transform the SQL string into an abstract syntax tree (AST). | no | +| `MvccStepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccStepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccBlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `MvccBlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `MvccKeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `SchemaChangerMode` | SchemaChangerMode is the mode that was used to execute the schema change, if any. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `schema_descriptor` + +An event of type `schema_descriptor` is an event for schema telemetry, whose purpose is +to take periodic snapshots of the cluster's SQL schema and publish them in +the telemetry log channel. For all intents and purposes, the data in such a +snapshot can be thought of the outer join of certain system tables: +namespace, descriptor, and at some point perhaps zones, etc. + +Snapshots are too large to conveniently be published as a single log event, +so instead they're broken down into SchemaDescriptor events which +contain the data in one record of this outer join projection. These events +are prefixed by a header (a SchemaSnapshotMetadata event). + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of the snapshot that this event is part of. | no | +| `ParentDatabaseID` | ParentDatabaseID matches the same key column in system.namespace. | no | +| `ParentSchemaID` | ParentSchemaID matches the same key column in system.namespace. | no | +| `Name` | Name matches the same key column in system.namespace. | no | +| `DescID` | DescID matches the 'id' column in system.namespace and system.descriptor. | no | +| `Desc` | Desc matches the 'descriptor' column in system.descriptor. Some contents of the descriptor may be redacted to prevent leaking PII. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_snapshot_metadata` + +An event of type `schema_snapshot_metadata` is an event describing a schema snapshot, which +is a set of SchemaDescriptor messages sharing the same SnapshotID. + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of this snapshot. | no | +| `NumRecords` | NumRecords is how many SchemaDescriptor events are in the snapshot. | no | +| `AsOfTimestamp` | AsOfTimestamp is when the snapshot was taken. This is equivalent to the timestamp given in the AS OF SYSTEM TIME clause when querying the namespace and descriptor tables in the system database. Expressed as nanoseconds since the Unix epoch. | no | +| `Errors` | Errors records any errors encountered when post-processing this snapshot, which includes the redaction of any potential PII. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Zone config events + +Events in this category pertain to zone configuration changes on +the SQL schema or system ranges. + +When zone configs apply to individual tables or other objects in a +SQL logical schema, they are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these zone config events are preserved +in each tenant's own `system.eventlog` table. + +When they apply to cluster-level ranges (e.g., the system zone config), +they are stored in the system tenant's own `system.eventlog` table. + +Events in this category are logged to the `OPS` channel. + + +### `remove_zone_config` + +An event of type `remove_zone_config` is recorded when a zone config is removed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `set_zone_config` + +An event of type `set_zone_config` is recorded when a zone config is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `ResolvedOldConfig` | The string representation of the resolved old zone config. This is not necessarily the same as the zone config that was previously set -- as it includes the resolved values of the zone config options. In other words, a zone config that hasn't been properly "set" yet (and inherits from its parent) will have a resolved_old_config that has details of the values it inherits from its parent. This is particularly useful to get a proper diff between the old and new zone config. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + + + + +## Enumeration types + +### `AuthFailReason` + +AuthFailReason is the inventory of possible reasons for an +authentication failure. + + +| Value | Textual alias in code or documentation | Description | +|--|--|--| +| 0 | UNKNOWN | is reported when the reason is unknown. | +| 1 | USER_RETRIEVAL_ERROR | occurs when there was an internal error accessing the principals. | +| 2 | USER_NOT_FOUND | occurs when the principal is unknown. | +| 3 | LOGIN_DISABLED | occurs when the user does not have LOGIN privileges. | +| 4 | METHOD_NOT_FOUND | occurs when no HBA rule matches or the method does not exist. | +| 5 | PRE_HOOK_ERROR | occurs when the authentication handshake encountered a protocol error. | +| 6 | CREDENTIALS_INVALID | occurs when the client-provided credentials were invalid. | +| 7 | CREDENTIALS_EXPIRED | occur when the credentials provided by the client are expired. | + + + diff --git a/src/current/_includes/cockroach-generated/release-23.1/logformats.md b/src/current/_includes/cockroach-generated/release-23.1/logformats.md new file mode 100644 index 00000000000..8d94fd08e1c --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-23.1/logformats.md @@ -0,0 +1,550 @@ + +The supported log output formats are documented below. + + +- [`crdb-v1`](#format-crdb-v1) + +- [`crdb-v1-count`](#format-crdb-v1-count) + +- [`crdb-v1-tty`](#format-crdb-v1-tty) + +- [`crdb-v1-tty-count`](#format-crdb-v1-tty-count) + +- [`crdb-v2`](#format-crdb-v2) + +- [`crdb-v2-tty`](#format-crdb-v2-tty) + +- [`json`](#format-json) + +- [`json-compact`](#format-json-compact) + +- [`json-fluent`](#format-json-fluent) + +- [`json-fluent-compact`](#format-json-fluent-compact) + + + +## Format `crdb-v1` + +This is the legacy file format used from CockroachDB v1.0. + +Each log entry is emitted using a common prefix, described below, +followed by: + +- The logging context tags enclosed between `[` and `]`, if any. It is possible + for this to be omitted if there were no context tags. +- the text of the log entry. + +Beware that the text of the log entry can span multiple lines. The following caveats apply: + + +- The text of the log entry can start with text enclosed between `[` and `]`. + If there were no logging tags to start with, it is not possible to distinguish between + logging context tag information and a `[...]` string in the main text of the + log entry. This means that this format is ambiguous. For an unambiguous alternative, + consider `crdb-v1-count`. + +- The text of the log entry can embed arbitrary application-level strings, + including strings that represent log entries. In particular, an accident + of implementation can cause the common entry prefix (described below) + to also appear on a line of its own, as part of the payload of a previous + log entry. There is no automated way to recognize when this occurs. + Care must be taken by a human observer to recognize these situations. + +- The log entry parser provided by CockroachDB to read log files is faulty + and is unable to recognize the aforementioned pitfall; nor can it read + entries larger than 64KiB successfully. Generally, use of this internal + log entry parser is discouraged for entries written with this format. + +See the newer format `crdb-v2` for an alternative +without these limitations. + +### Header lines + +At the beginning of each file, a header is printed using a similar format as +regular log entries. This header reports when the file was created, +which parameters were used to start the server, the server identifiers +if known, and other metadata about the running process. + +- This header appears to be logged at severity `INFO` (with an `I` prefix + at the start of the line) even though it does not really have a severity. +- The header is printed unconditionally even when a filter is configured to + omit entries at the `INFO` level. + +### Common log entry prefix + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (omitted if zero for use by tests). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. | +| line | The line number where the entry originated. | +| marker | Redactability marker ` + redactableIndicator + ` (see below for details). | + +The redactability marker can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. + +If the marker ` + redactableIndicator + ` is present, the remainder of the log entry +contains delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + + +## Format `crdb-v1-count` + +This is an alternative, backward-compatible legacy file format used from CockroachDB v2.0. + +Each log entry is emitted using a common prefix, described below, +followed by the text of the log entry. + +Beware that the text of the log entry can span multiple lines. The following caveats apply: + + +- The text of the log entry can embed arbitrary application-level strings, + including strings that represent log entries. In particular, an accident + of implementation can cause the common entry prefix (described below) + to also appear on a line of its own, as part of the payload of a previous + log entry. There is no automated way to recognize when this occurs. + Care must be taken by a human observer to recognize these situations. + +- The log entry parser provided by CockroachDB to read log files is faulty + and is unable to recognize the aforementioned pitfall; nor can it read + entries larger than 64KiB successfully. Generally, use of this internal + log entry parser is discouraged for entries written with this format. + +See the newer format `crdb-v2` for an alternative +without these limitations. + +### Header lines + +At the beginning of each file, a header is printed using a similar format as +regular log entries. This header reports when the file was created, +which parameters were used to start the server, the server identifiers +if known, and other metadata about the running process. + +- This header appears to be logged at severity `INFO` (with an `I` prefix + at the start of the line) even though it does not really have a severity. +- The header is printed unconditionally even when a filter is configured to + omit entries at the `INFO` level. + +### Common log entry prefix + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker tags counter + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (omitted if zero for use by tests). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. | +| line | The line number where the entry originated. | +| marker | Redactability marker ` + redactableIndicator + ` (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. May be absent. | +| counter | The entry counter. Always present. | + +The redactability marker can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. + +If the marker ` + redactableIndicator + ` is present, the remainder of the log entry +contains delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + + +## Format `crdb-v1-tty` + +Same textual format as `crdb-v1`. + +In addition, if the output stream happens to be a VT-compatible terminal, +and the flag `no-color` was *not* set in the configuration, the entries +are decorated using ANSI color codes. + +## Format `crdb-v1-tty-count` + +Same textual format as `crdb-v1-count`. + +In addition, if the output stream happens to be a VT-compatible terminal, +and the flag `no-color` was *not* set in the configuration, the entries +are decorated using ANSI color codes. + +## Format `crdb-v2` + +This is the main file format used from CockroachDB v21.1. + +Each log entry is emitted using a common prefix, described below, +followed by the text of the log entry. + +### Entry format + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker [tags...] counter cont + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (zero when cannot be determined). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. Also see below. | +| line | The line number where the entry originated. | +| marker | Redactability marker "⋮" (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. See below. | +| counter | The optional entry counter (see below for details). | +| cont | Continuation mark for structured and multi-line entries. See below. | + +The `chan@` prefix before the file name indicates the logging channel, +and is omitted if the channel is `DEV`. + +The file name may be prefixed by the string `(gostd) ` to indicate +that the log entry was produced inside the Go standard library, instead +of a CockroachDB component. Entry parsers must be configured to ignore this prefix +when present. + +`marker` can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. +If the marker "⋮" is present, the remainder of the log entry +contains delimiters (‹...›) +around fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +when log redaction is requested. + +The logging `tags` are enclosed between square brackets `[...]`, +and the syntax `[-]` is used when there are no logging tags +associated with the log entry. + +`counter` is numeric, and is incremented for every +log entry emitted to this sink. (There is thus one counter sequence per +sink.) For entries that do not have a counter value +associated (e.g., header entries in file sinks), the counter position +in the common prefix is empty: `tags` is then +followed by two ASCII space characters, instead of one space; the `counter`, +and another space. The presence of the two ASCII spaces indicates +reliably that no counter was present. + +`cont` is a format/continuation indicator: + +| Continuation indicator | ASCII | Description | +|------------------------|-------|--| +| space | 0x32 | Start of an unstructured entry. | +| equal sign, "=" | 0x3d | Start of a structured entry. | +| exclamation mark, "!" | 0x21 | Start of an embedded stack trace. | +| plus sign, "+" | 0x2b | Continuation of a multi-line entry. The payload contains a newline character at this position. | +| vertical bar | 0x7c | Continuation of a large entry. | + +### Examples + +Example single-line unstructured entry: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 started with engine type ‹2› +~~~ + +Example multi-line unstructured entry: + +~~~ +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 node startup completed: +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 +CockroachDB node starting at 2021-01-16 21:49 (took 0.0s) +~~~ + +Example structured entry: + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventType":"node_restart"} +~~~ + +Example long entries broken up into multiple lines: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.... +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 |aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +~~~ + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventTy... +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 |pe":"node_restart"} +~~~ + +### Backward-compatibility notes + +Entries in this format can be read by most `crdb-v1` log parsers, +in particular the one included in the DB console and +also the [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +facility. + +However, implementers of previous version parsers must +understand that the logging tags field is now always +included, and the lack of logging tags is included +by a tag string set to `[-]`. + +Likewise, the entry counter is now also always included, +and there is a special character after `counter` +to indicate whether the remainder of the line is a +structured entry, or a continuation of a previous entry. + +Finally, in the previous format, structured entries +were prefixed with the string `Structured entry: `. In +the new format, they are prefixed by the `=` continuation +indicator. + + +## Format `crdb-v2-tty` + +Same textual format as `crdb-v2`. + +In addition, if the output stream happens to be a VT-compatible terminal, +and the flag `no-color` was *not* set in the configuration, the entries +are decorated using ANSI color codes. + +## Format `json` + +This format emits log entries as a JSON payload. + +The JSON object is guaranteed to not contain unescaped newlines +or other special characters, and the entry as a whole is followed +by a newline character. This makes the format suitable for +processing over a stream unambiguously. + +Each entry contains at least the following fields: + +| Field | Description | +|-------|-------------| +| `file` | The name of the source file where the event was emitted. | +| `goroutine` | The identifier of the goroutine where the event was emitted. | +| `line` | The line number where the event was emitted in the source. | +| `redactable` | Whether the payload is redactable (see below for details). | +| `timestamp` | The timestamp at which the event was emitted on the logging channel. | +| `version` | The binary version with which the event was generated. | + + +After a couple of *header* entries written at the beginning of each log sink, +all subsequent log entries also contain the following fields: + +| Field | Description | +|---------------------|-------------| +| `channel` | The name of the logging channel where the event was sent. | +| `severity` | The severity of the event. | +| `channel_numeric` | The numeric identifier for the logging channel where the event was sent. | +| `entry_counter` | The entry number on this logging sink, relative to the last process restart. | +| `severity_numeric` | The numeric value of the severity of the event. | + + +Additionally, the following fields are conditionally present: + +| Field | Description | +|---------------------|-------------| +| `node_id` | The node ID where the event was generated, once known. Only reported for single-tenant or KV servers. | +| `cluster_id` | The cluster ID where the event was generated, once known. Only reported for single-tenant of KV servers. | +| `instance_id` | The SQL instance ID where the event was generated, once known. Only reported for multi-tenant SQL servers. | +| `tenant_id` | The SQL tenant ID where the event was generated, once known. Only reported for multi-tenant SQL servers. | +| `tags` | The logging context tags for the entry, if there were context tags. | +| `message` | For unstructured events, the flat text payload. | +| `event` | The logging event, if structured (see below for details). | +| `stacks` | Goroutine stacks, for fatal events. | + +When an entry is structured, the `event` field maps to a dictionary +whose structure is one of the documented structured events. See the [reference documentation](eventlog.html) +for structured events for a list of possible payloads. + +When the entry is marked as `redactable`, the `tags`, `message`, and/or `event` payloads +contain delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + + + + +## Format `json-compact` + +This format emits log entries as a JSON payload. + +The JSON object is guaranteed to not contain unescaped newlines +or other special characters, and the entry as a whole is followed +by a newline character. This makes the format suitable for +processing over a stream unambiguously. + +Each entry contains at least the following fields: + +| Field | Description | +|-------|-------------| +| `f` | The name of the source file where the event was emitted. | +| `g` | The identifier of the goroutine where the event was emitted. | +| `l` | The line number where the event was emitted in the source. | +| `r` | Whether the payload is redactable (see below for details). | +| `t` | The timestamp at which the event was emitted on the logging channel. | +| `v` | The binary version with which the event was generated. | + + +After a couple of *header* entries written at the beginning of each log sink, +all subsequent log entries also contain the following fields: + +| Field | Description | +|---------------------|-------------| +| `C` | The name of the logging channel where the event was sent. | +| `sev` | The severity of the event. | +| `c` | The numeric identifier for the logging channel where the event was sent. | +| `n` | The entry number on this logging sink, relative to the last process restart. | +| `s` | The numeric value of the severity of the event. | + + +Additionally, the following fields are conditionally present: + +| Field | Description | +|---------------------|-------------| +| `N` | The node ID where the event was generated, once known. Only reported for single-tenant or KV servers. | +| `x` | The cluster ID where the event was generated, once known. Only reported for single-tenant of KV servers. | +| `q` | The SQL instance ID where the event was generated, once known. Only reported for multi-tenant SQL servers. | +| `T` | The SQL tenant ID where the event was generated, once known. Only reported for multi-tenant SQL servers. | +| `tags` | The logging context tags for the entry, if there were context tags. | +| `message` | For unstructured events, the flat text payload. | +| `event` | The logging event, if structured (see below for details). | +| `stacks` | Goroutine stacks, for fatal events. | + +When an entry is structured, the `event` field maps to a dictionary +whose structure is one of the documented structured events. See the [reference documentation](eventlog.html) +for structured events for a list of possible payloads. + +When the entry is marked as `redactable`, the `tags`, `message`, and/or `event` payloads +contain delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + + + + +## Format `json-fluent` + +This format emits log entries as a JSON payload. + +The JSON object is guaranteed to not contain unescaped newlines +or other special characters, and the entry as a whole is followed +by a newline character. This makes the format suitable for +processing over a stream unambiguously. + +Each entry contains at least the following fields: + +| Field | Description | +|-------|-------------| +| `tag` | A Fluent tag for the event, formed by the process name and the logging channel. | +| `file` | The name of the source file where the event was emitted. | +| `goroutine` | The identifier of the goroutine where the event was emitted. | +| `line` | The line number where the event was emitted in the source. | +| `redactable` | Whether the payload is redactable (see below for details). | +| `timestamp` | The timestamp at which the event was emitted on the logging channel. | +| `version` | The binary version with which the event was generated. | + + +After a couple of *header* entries written at the beginning of each log sink, +all subsequent log entries also contain the following fields: + +| Field | Description | +|---------------------|-------------| +| `channel` | The name of the logging channel where the event was sent. | +| `severity` | The severity of the event. | +| `channel_numeric` | The numeric identifier for the logging channel where the event was sent. | +| `entry_counter` | The entry number on this logging sink, relative to the last process restart. | +| `severity_numeric` | The numeric value of the severity of the event. | + + +Additionally, the following fields are conditionally present: + +| Field | Description | +|---------------------|-------------| +| `node_id` | The node ID where the event was generated, once known. Only reported for single-tenant or KV servers. | +| `cluster_id` | The cluster ID where the event was generated, once known. Only reported for single-tenant of KV servers. | +| `instance_id` | The SQL instance ID where the event was generated, once known. Only reported for multi-tenant SQL servers. | +| `tenant_id` | The SQL tenant ID where the event was generated, once known. Only reported for multi-tenant SQL servers. | +| `tags` | The logging context tags for the entry, if there were context tags. | +| `message` | For unstructured events, the flat text payload. | +| `event` | The logging event, if structured (see below for details). | +| `stacks` | Goroutine stacks, for fatal events. | + +When an entry is structured, the `event` field maps to a dictionary +whose structure is one of the documented structured events. See the [reference documentation](eventlog.html) +for structured events for a list of possible payloads. + +When the entry is marked as `redactable`, the `tags`, `message`, and/or `event` payloads +contain delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + + + + +## Format `json-fluent-compact` + +This format emits log entries as a JSON payload. + +The JSON object is guaranteed to not contain unescaped newlines +or other special characters, and the entry as a whole is followed +by a newline character. This makes the format suitable for +processing over a stream unambiguously. + +Each entry contains at least the following fields: + +| Field | Description | +|-------|-------------| +| `tag` | A Fluent tag for the event, formed by the process name and the logging channel. | +| `f` | The name of the source file where the event was emitted. | +| `g` | The identifier of the goroutine where the event was emitted. | +| `l` | The line number where the event was emitted in the source. | +| `r` | Whether the payload is redactable (see below for details). | +| `t` | The timestamp at which the event was emitted on the logging channel. | +| `v` | The binary version with which the event was generated. | + + +After a couple of *header* entries written at the beginning of each log sink, +all subsequent log entries also contain the following fields: + +| Field | Description | +|---------------------|-------------| +| `C` | The name of the logging channel where the event was sent. | +| `sev` | The severity of the event. | +| `c` | The numeric identifier for the logging channel where the event was sent. | +| `n` | The entry number on this logging sink, relative to the last process restart. | +| `s` | The numeric value of the severity of the event. | + + +Additionally, the following fields are conditionally present: + +| Field | Description | +|---------------------|-------------| +| `N` | The node ID where the event was generated, once known. Only reported for single-tenant or KV servers. | +| `x` | The cluster ID where the event was generated, once known. Only reported for single-tenant of KV servers. | +| `q` | The SQL instance ID where the event was generated, once known. Only reported for multi-tenant SQL servers. | +| `T` | The SQL tenant ID where the event was generated, once known. Only reported for multi-tenant SQL servers. | +| `tags` | The logging context tags for the entry, if there were context tags. | +| `message` | For unstructured events, the flat text payload. | +| `event` | The logging event, if structured (see below for details). | +| `stacks` | Goroutine stacks, for fatal events. | + +When an entry is structured, the `event` field maps to a dictionary +whose structure is one of the documented structured events. See the [reference documentation](eventlog.html) +for structured events for a list of possible payloads. + +When the entry is marked as `redactable`, the `tags`, `message`, and/or `event` payloads +contain delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + + + + diff --git a/src/current/_includes/cockroach-generated/release-23.1/logging.md b/src/current/_includes/cockroach-generated/release-23.1/logging.md new file mode 100644 index 00000000000..81dd8bbe287 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-23.1/logging.md @@ -0,0 +1,179 @@ +## Logging levels (severities) + +### INFO + +The `INFO` severity is used for informational messages that do not +require action. + +### WARNING + +The `WARNING` severity is used for situations which may require special handling, +where normal operation is expected to resume automatically. + +### ERROR + +The `ERROR` severity is used for situations that require special handling, +where normal operation could not proceed as expected. +Other operations can continue mostly unaffected. + +### FATAL + +The `FATAL` severity is used for situations that require an immedate, hard +server shutdown. A report is also sent to telemetry if telemetry +is enabled. + + +## Logging channels + +### `DEV` + +The `DEV` channel is used during development to collect log +details useful for troubleshooting that fall outside the +scope of other channels. It is also the default logging +channel for events not associated with a channel. + +This channel is special in that there are no constraints as to +what may or may not be logged on it. Conversely, users in +production deployments are invited to not collect `DEV` logs in +centralized logging facilities, because they likely contain +sensitive operational data. +See [Configure logs](configure-logs.html#dev-channel). + +### `OPS` + +The `OPS` channel is used to report "point" operational events, +initiated by user operators or automation: + + - Operator or system actions on server processes: process starts, + stops, shutdowns, crashes (if they can be logged), + including each time: command-line parameters, current version being run + - Actions that impact the topology of a cluster: node additions, + removals, decommissions, etc. + - Job-related initiation or termination + - [Cluster setting](cluster-settings.html) changes + - [Zone configuration](configure-replication-zones.html) changes + +### `HEALTH` + +The `HEALTH` channel is used to report "background" operational +events, initiated by CockroachDB or reporting on automatic processes: + + - Current resource usage, including critical resource usage + - Node-node connection events, including connection errors and + gossip details + - Range and table leasing events + - Up- and down-replication, range unavailability + +### `STORAGE` + +The `STORAGE` channel is used to report low-level storage +layer events (RocksDB/Pebble). + +### `SESSIONS` + +The `SESSIONS` channel is used to report client network activity when enabled via +the `server.auth_log.sql_connections.enabled` and/or +`server.auth_log.sql_sessions.enabled` [cluster setting](cluster-settings.html): + + - Connections opened/closed + - Authentication events: logins, failed attempts + - Session and query cancellation + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_SCHEMA` + +The `SQL_SCHEMA` channel is used to report changes to the +SQL logical schema, excluding privilege and ownership changes +(which are reported separately on the `PRIVILEGES` channel) and +zone configuration changes (which go to the `OPS` channel). + +This includes: + + - Database/schema/table/sequence/view/type creation + - Adding/removing/changing table columns + - Changing sequence parameters + +`SQL_SCHEMA` events generally comprise changes to the schema that affect the +functional behavior of client apps using stored objects. + +### `USER_ADMIN` + +The `USER_ADMIN` channel is used to report changes +in users and roles, including: + + - Users added/dropped + - Changes to authentication credentials (e.g., passwords, validity, etc.) + - Role grants/revocations + - Role option grants/revocations + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `PRIVILEGES` + +The `PRIVILEGES` channel is used to report data +authorization changes, including: + + - Privilege grants/revocations on database, objects, etc. + - Object ownership changes + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SENSITIVE_ACCESS` + +The `SENSITIVE_ACCESS` channel is used to report SQL +data access to sensitive data: + + - Data access audit events (when table audit is enabled via + [ALTER TABLE ... EXPERIMENTAL_AUDIT](alter-table.html#experimental_audit)) + - Data access audit events (when role-based audit is enabled via + [`sql.log.user_audit` cluster setting](role-based-audit-logging.html#syntax-of-audit-settings)) + - SQL statements executed by users with the admin role + - Operations that write to system tables + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_EXEC` + +The `SQL_EXEC` channel is used to report SQL execution on +behalf of client connections: + + - Logical SQL statement executions (when enabled via the + `sql.trace.log_statement_execute` [cluster setting](cluster-settings.html)) + - uncaught Go panic errors during the execution of a SQL statement. + +### `SQL_PERF` + +The `SQL_PERF` channel is used to report SQL executions +that are marked as "out of the ordinary" +to facilitate performance investigations. +This includes the SQL "slow query log". + +Arguably, this channel overlaps with `SQL_EXEC`. +However, we keep both channels separate for backward compatibility +with versions prior to v21.1, where the corresponding events +were redirected to separate files. + +### `SQL_INTERNAL_PERF` + +The `SQL_INTERNAL_PERF` channel is like the `SQL_PERF` channel, but is aimed at +helping developers of CockroachDB itself. It exists as a separate +channel so as to not pollute the `SQL_PERF` logging output with +internal troubleshooting details. + +### `TELEMETRY` + +The `TELEMETRY` channel reports telemetry events. Telemetry events describe +feature usage within CockroachDB and anonymizes any application- +specific data. + +### `KV_DISTRIBUTION` + +The `KV_DISTRIBUTION` channel is used to report data distribution events, such as moving +replicas between stores in the cluster, or adding (removing) replicas to +ranges. + diff --git a/src/current/_includes/cockroach-generated/release-23.1/settings/settings.html b/src/current/_includes/cockroach-generated/release-23.1/settings/settings.html new file mode 100644 index 00000000000..ad0688d7306 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-23.1/settings/settings.html @@ -0,0 +1,271 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingTypeDefaultDescription
admission.disk_bandwidth_tokens.elastic.enabled
booleantruewhen true, and provisioned bandwidth for the disk corresponding to a store is configured, tokens for elastic work will be limited if disk bandwidth becomes a bottleneck
admission.epoch_lifo.enabled
booleanfalsewhen true, epoch-LIFO behavior is enabled when there is significant delay in admission
admission.epoch_lifo.epoch_closing_delta_duration
duration5msthe delta duration before closing an epoch, for epoch-LIFO admission control ordering
admission.epoch_lifo.epoch_duration
duration100msthe duration of an epoch, for epoch-LIFO admission control ordering
admission.epoch_lifo.queue_delay_threshold_to_switch_to_lifo
duration105msthe queue delay encountered by a (tenant,priority) for switching to epoch-LIFO ordering
admission.kv.enabled
booleantruewhen true, work performed by the KV layer is subject to admission control
admission.kv.stores.tenant_weights.enabled
booleanfalsewhen true, tenant weights are enabled for KV-stores admission control
admission.kv.tenant_weights.enabled
booleanfalsewhen true, tenant weights are enabled for KV admission control
admission.sql_kv_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a KV response is subject to admission control
admission.sql_sql_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a DistSQL response is subject to admission control
bulkio.backup.deprecated_full_backup_with_subdir.enabled
booleanfalsewhen true, a backup command with a user specified subdirectory will create a full backup at the subdirectory if no backup already exists at that subdirectory.
bulkio.backup.file_size
byte size128 MiBtarget size for individual data files produced during BACKUP
bulkio.backup.read_timeout
duration5m0samount of time after which a read attempt is considered timed out, which causes the backup to fail
bulkio.backup.read_with_priority_after
duration1m0samount of time since the read-as-of time above which a BACKUP should use priority when retrying reads
bulkio.stream_ingestion.minimum_flush_interval
duration5sthe minimum timestamp between flushes; flushes may still occur if internal buffers fill up
changefeed.aggregator.flush_jitter
float0jitter aggregator flushes as a fraction of min_checkpoint_frequency. This setting has no effect if min_checkpoint_frequency is set to 0.
changefeed.backfill.scan_request_size
integer524288the maximum number of bytes returned by each scan request
changefeed.balance_range_distribution.enable
booleanfalseif enabled, the ranges are balanced equally among all nodes
changefeed.batch_reduction_retry_enabled
booleanfalseif true, kafka changefeeds upon erroring on an oversized batch will attempt to resend the messages with progressively lower batch sizes
changefeed.event_consumer_worker_queue_size
integer16if changefeed.event_consumer_workers is enabled, this setting sets the maxmimum number of events which a worker can buffer
changefeed.event_consumer_workers
integer0the number of workers to use when processing events: <0 disables, 0 assigns a reasonable default, >0 assigns the setting value. for experimental/core changefeeds and changefeeds using parquet format, this is disabled
changefeed.fast_gzip.enabled
booleantrueuse fast gzip implementation
changefeed.lagging_ranges_polling_interval
duration1m0sthe polling rate at which lagging ranges are checked and corresponding metrics are updated. will be removed in v23.2 onwards
changefeed.lagging_ranges_threshold
duration3m0sspecifies the duration by which a range must be lagging behind the present to be considered as 'lagging' behind in metrics. will be removed in v23.2 in favor of a changefeed option
changefeed.node_throttle_config
stringspecifies node level throttling configuration for all changefeeeds
changefeed.schema_feed.read_with_priority_after
duration1m0sretry with high priority if we were not able to read descriptors for too long; 0 disables
changefeed.sink_io_workers
integer0the number of workers used by changefeeds when sending requests to the sink (currently webhook only): <0 disables, 0 assigns a reasonable default, >0 assigns the setting value.
cloudstorage.azure.concurrent_upload_buffers
integer1controls the number of concurrent buffers that will be used by the Azure client when uploading chunks.Each buffer can buffer up to cloudstorage.write_chunk.size of memory during an upload
cloudstorage.http.custom_ca
stringcustom root CA (appended to system's default CAs) for verifying certificates when interacting with HTTPS storage
cloudstorage.timeout
duration10m0sthe timeout for import/export storage operations
cluster.organization
stringorganization name
cluster.preserve_downgrade_option
stringdisable (automatic or manual) cluster version upgrade from the specified version until reset
diagnostics.active_query_dumps.enabled
booleantrueexperimental: enable dumping of anonymized active queries to disk when node is under memory pressure
diagnostics.forced_sql_stat_reset.interval
duration2h0m0sinterval after which the reported SQL Stats are reset even if not collected by telemetry reporter. It has a max value of 24H.
diagnostics.reporting.enabled
booleantrueenable reporting diagnostic metrics to cockroach labs, but is ignored for Trial or Free licenses
diagnostics.reporting.interval
duration1h0m0sinterval at which diagnostics data should be reported
enterprise.license
stringthe encoded cluster license
external.graphite.endpoint
stringif nonempty, push server metrics to the Graphite or Carbon server at the specified host:port
external.graphite.interval
duration10sthe interval at which metrics are pushed to Graphite (if enabled)
feature.backup.enabled
booleantrueset to true to enable backups, false to disable; default is true
feature.changefeed.enabled
booleantrueset to true to enable changefeeds, false to disable; default is true
feature.export.enabled
booleantrueset to true to enable exports, false to disable; default is true
feature.import.enabled
booleantrueset to true to enable imports, false to disable; default is true
feature.restore.enabled
booleantrueset to true to enable restore, false to disable; default is true
feature.schema_change.enabled
booleantrueset to true to enable schema changes, false to disable; default is true
feature.stats.enabled
booleantrueset to true to enable CREATE STATISTICS/ANALYZE, false to disable; default is true
jobs.retention_time
duration336h0m0sthe amount of time for which records for completed jobs are retained
kv.allocator.lease_rebalance_threshold
float0.05minimum fraction away from the mean a store's lease count can be before it is considered for lease-transfers
kv.allocator.load_based_lease_rebalancing.enabled
booleantrueset to enable rebalancing of range leases based on load and latency
kv.allocator.load_based_rebalancing
enumerationleases and replicaswhether to rebalance based on the distribution of load across stores [off = 0, leases = 1, leases and replicas = 2]
kv.allocator.load_based_rebalancing.objective
enumerationcpuwhat objective does the cluster use to rebalance; if set to `qps` the cluster will attempt to balance qps among stores, if set to `cpu` the cluster will attempt to balance cpu usage among stores [qps = 0, cpu = 1]
kv.allocator.load_based_rebalancing_interval
duration1m0sthe rough interval at which each store will check for load-based lease / replica rebalancing opportunities
kv.allocator.qps_rebalance_threshold
float0.1minimum fraction away from the mean a store's QPS (such as queries per second) can be before it is considered overfull or underfull
kv.allocator.range_rebalance_threshold
float0.05minimum fraction away from the mean a store's range count can be before it is considered overfull or underfull
kv.allocator.store_cpu_rebalance_threshold
float0.1minimum fraction away from the mean a store's cpu usage can be before it is considered overfull or underfull
kv.bulk_io_write.max_rate
byte size1.0 TiBthe rate limit (bytes/sec) to use for writes to disk on behalf of bulk io ops
kv.bulk_sst.max_allowed_overage
byte size64 MiBif positive, allowed size in excess of target size for SSTs from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memory
kv.bulk_sst.target_size
byte size16 MiBtarget size for SSTs emitted from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memory
kv.closed_timestamp.follower_reads_enabled
booleantrueallow (all) replicas to serve consistent historical reads based on closed timestamp information
kv.log_range_and_node_events.enabled
booleantrueset to true to transactionally log range events (e.g., split, merge, add/remove voter/non-voter) into system.rangelogand node join and restart events into system.eventolog
kv.protectedts.reconciliation.interval
duration5m0sthe frequency for reconciling jobs with protected timestamp records
kv.range_split.by_load_enabled
booleantrueallow automatic splits of ranges based on where load is concentrated
kv.range_split.load_cpu_threshold
duration500msthe CPU use per second over which, the range becomes a candidate for load based splitting
kv.range_split.load_qps_threshold
integer2500the QPS over which, the range becomes a candidate for load based splitting
kv.rangefeed.enabled
booleanfalseif set, rangefeed registration is enabled
kv.rangefeed.range_stuck_threshold
duration1m0srestart rangefeeds if they don't emit anything for the specified threshold; 0 disables (kv.closed_timestamp.side_transport_interval takes precedence)
kv.replica_circuit_breaker.slow_replication_threshold
duration1m0sduration after which slow proposals trip the per-Replica circuit breaker (zero duration disables breakers)
kv.replica_stats.addsst_request_size_factor
integer50000the divisor that is applied to addsstable request sizes, then recorded in a leaseholders QPS; 0 means all requests are treated as cost 1
kv.replication_reports.interval
duration1m0sthe frequency for generating the replication_constraint_stats, replication_stats_report and replication_critical_localities reports (set to 0 to disable)
kv.snapshot_rebalance.max_rate
byte size32 MiBthe rate limit (bytes/sec) to use for rebalance and upreplication snapshots
kv.snapshot_recovery.max_rate
byte size32 MiBthe rate limit (bytes/sec) to use for recovery snapshots
kv.transaction.max_intents_bytes
integer4194304maximum number of bytes used to track locks in transactions
kv.transaction.max_refresh_spans_bytes
integer4194304maximum number of bytes used to track refresh spans in serializable transactions
kv.transaction.reject_over_max_intents_budget.enabled
booleanfalseif set, transactions that exceed their lock tracking budget (kv.transaction.max_intents_bytes) are rejected instead of having their lock spans imprecisely compressed
kvadmission.store.provisioned_bandwidth
byte size0 Bif set to a non-zero value, this is used as the provisioned bandwidth (in bytes/s), for each store. It can be over-ridden on a per-store basis using the --store flag
schedules.backup.gc_protection.enabled
booleantrueenable chaining of GC protection across backups run as part of a schedule
security.ocsp.mode
enumerationoffuse OCSP to check whether TLS certificates are revoked. If the OCSP server is unreachable, in strict mode all certificates will be rejected and in lax mode all certificates will be accepted. [off = 0, lax = 1, strict = 2]
security.ocsp.timeout
duration3stimeout before considering the OCSP server unreachable
server.auth_log.sql_connections.enabled
booleanfalseif set, log SQL client connect and disconnect events to the SESSIONS log channel (note: may hinder performance on loaded nodes)
server.auth_log.sql_sessions.enabled
booleanfalseif set, log verbose SQL session authentication events to the SESSIONS log channel (note: may hinder performance on loaded nodes). Session start and end events are always logged regardless of this setting; disable the SESSIONS log channel to suppress them.
server.authentication_cache.enabled
booleantrueenables a cache used during authentication to avoid lookups to system tables when retrieving per-user authentication-related information
server.child_metrics.enabled
booleanfalseenables the exporting of child metrics, additional prometheus time series with extra labels
server.client_cert_expiration_cache.capacity
integer1000the maximum number of client cert expirations stored
server.clock.forward_jump_check_enabled
booleanfalseif enabled, forward clock jumps > max_offset/2 will cause a panic
server.clock.persist_upper_bound_interval
duration0sthe interval between persisting the wall time upper bound of the clock. The clock does not generate a wall time greater than the persisted timestamp and will panic if it sees a wall time greater than this value. When cockroach starts, it waits for the wall time to catch-up till this persisted timestamp. This guarantees monotonic wall time across server restarts. Not setting this or setting a value of 0 disables this feature.
server.consistency_check.max_rate
byte size8.0 MiBthe rate limit (bytes/sec) to use for consistency checks; used in conjunction with server.consistency_check.interval to control the frequency of consistency checks. Note that setting this too high can negatively impact performance.
server.controller.default_tenant
stringsystemname of the tenant to use to serve requests when clients don't specify a tenant
server.eventlog.enabled
booleantrueif set, logged notable events are also stored in the table system.eventlog
server.eventlog.ttl
duration2160h0m0sif nonzero, entries in system.eventlog older than this duration are periodically purged
server.host_based_authentication.configuration
stringhost-based authentication configuration to use during connection authentication
server.hot_ranges_request.node.timeout
duration5m0sthe duration allowed for a single node to return hot range data before the request is cancelled; if set to 0, there is no timeout
server.hsts.enabled
booleanfalseif true, HSTS headers will be sent along with all HTTP requests. The headers will contain a max-age setting of one year. Browsers honoring the header will always use HTTPS to access the DB Console. Ensure that TLS is correctly configured prior to enabling.
server.http.base_path
string/path to redirect the user to upon succcessful login
server.identity_map.configuration
stringsystem-identity to database-username mappings
server.log_gc.max_deletions_per_cycle
integer1000the maximum number of entries to delete on each purge of log-like system tables
server.log_gc.period
duration1h0m0sthe period at which log-like system tables are checked for old entries
server.max_connections_per_gateway
integer-1the maximum number of non-superuser SQL connections per gateway allowed at a given time (note: this will only limit future connection attempts and will not affect already established connections). Negative values result in unlimited number of connections. Superusers are not affected by this limit.
server.max_open_transactions_per_gateway
integer-1the maximum number of open SQL transactions per gateway allowed at a given time. Negative values result in unlimited number of connections. Superusers are not affected by this limit.
server.oidc_authentication.autologin
booleanfalseif true, logged-out visitors to the DB Console will be automatically redirected to the OIDC login endpoint
server.oidc_authentication.button_text
stringLog in with your OIDC providertext to show on button on DB Console login page to login with your OIDC provider (only shown if OIDC is enabled)
server.oidc_authentication.claim_json_key
stringsets JSON key of principal to extract from payload after OIDC authentication completes (usually email or sid)
server.oidc_authentication.client_id
stringsets OIDC client id
server.oidc_authentication.client_secret
stringsets OIDC client secret
server.oidc_authentication.enabled
booleanfalseenables or disabled OIDC login for the DB Console
server.oidc_authentication.principal_regex
string(.+)regular expression to apply to extracted principal (see claim_json_key setting) to translate to SQL user (golang regex format, must include 1 grouping to extract)
server.oidc_authentication.provider_url
stringsets OIDC provider URL ({provider_url}/.well-known/openid-configuration must resolve)
server.oidc_authentication.redirect_url
stringhttps://localhost:8080/oidc/v1/callbacksets OIDC redirect URL via a URL string or a JSON string containing a required `redirect_urls` key with an object that maps from region keys to URL strings (URLs should point to your load balancer and must route to the path /oidc/v1/callback)
server.oidc_authentication.scopes
stringopenidsets OIDC scopes to include with authentication request (space delimited list of strings, required to start with `openid`)
server.rangelog.ttl
duration720h0m0sif nonzero, entries in system.rangelog older than this duration are periodically purged
server.secondary_tenants.redact_trace.enabled
booleantruecontrols if server side traces are redacted for tenant operations
server.shutdown.connection_wait
duration0sthe maximum amount of time a server waits for all SQL connections to be closed before proceeding with a drain. (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)
server.shutdown.drain_wait
duration0sthe amount of time a server waits in an unready state before proceeding with a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting. --drain-wait is to specify the duration of the whole draining process, while server.shutdown.drain_wait is to set the wait time for health probes to notice that the node is not ready.)
server.shutdown.lease_transfer_wait
duration5sthe timeout for a single iteration of the range lease transfer phase of draining (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)
server.shutdown.query_wait
duration10sthe timeout for waiting for active queries to finish during a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)
server.time_until_store_dead
duration5m0sthe time after which if there is no new gossiped information about a store, it is considered dead
server.user_login.cert_password_method.auto_scram_promotion.enabled
booleantruewhether to automatically promote cert-password authentication to use SCRAM
server.user_login.downgrade_scram_stored_passwords_to_bcrypt.enabled
booleantrueif server.user_login.password_encryption=crdb-bcrypt, this controls whether to automatically re-encode stored passwords using scram-sha-256 to crdb-bcrypt
server.user_login.min_password_length
integer1the minimum length accepted for passwords set in cleartext via SQL. Note that a value lower than 1 is ignored: passwords cannot be empty in any case.
server.user_login.password_encryption
enumerationscram-sha-256which hash method to use to encode cleartext passwords passed via ALTER/CREATE USER/ROLE WITH PASSWORD [crdb-bcrypt = 2, scram-sha-256 = 3]
server.user_login.password_hashes.default_cost.crdb_bcrypt
integer10the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method crdb-bcrypt (allowed range: 4-31)
server.user_login.password_hashes.default_cost.scram_sha_256
integer10610the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method scram-sha-256 (allowed range: 4096-240000000000)
server.user_login.rehash_scram_stored_passwords_on_cost_change.enabled
booleantrueif server.user_login.password_hashes.default_cost.scram_sha_256 differs from, the cost in a stored hash, this controls whether to automatically re-encode stored passwords using scram-sha-256 with the new default cost
server.user_login.timeout
duration10stimeout after which client authentication times out if some system range is unavailable (0 = no timeout)
server.user_login.upgrade_bcrypt_stored_passwords_to_scram.enabled
booleantrueif server.user_login.password_encryption=scram-sha-256, this controls whether to automatically re-encode stored passwords using crdb-bcrypt to scram-sha-256
server.web_session.purge.ttl
duration1h0m0sif nonzero, entries in system.web_sessions older than this duration are periodically purged
server.web_session_timeout
duration168h0m0sthe duration that a newly created web session will be valid
sql.auth.change_own_password.enabled
booleanfalsecontrols whether a user is allowed to change their own password, even if they have no other privileges
sql.auth.createrole_allows_grant_role_membership.enabled
booleanfalseif set, users with CREATEROLE privilege can grant/revoke membership in roles
sql.auth.grant_option_for_owner.enabled
booleantruedetermines whether the GRANT OPTION for privileges is implicitly given to the owner of an object
sql.auth.grant_option_inheritance.enabled
booleantruedetermines whether the GRANT OPTION for privileges is inherited through role membership
sql.auth.modify_cluster_setting_applies_to_all.enabled
booleantruea bool which indicates whether MODIFYCLUSTERSETTING is able to set all cluster settings or only settings with the sql.defaults prefix (deprecated)
sql.auth.resolve_membership_single_scan.enabled
booleantruedetermines whether to populate the role membership cache with a single scan
sql.closed_session_cache.capacity
integer1000the maximum number of sessions in the cache
sql.closed_session_cache.time_to_live
integer3600the maximum time to live, in seconds
sql.contention.event_store.capacity
byte size64 MiBthe in-memory storage capacity per-node of contention event store
sql.contention.event_store.duration_threshold
duration0sminimum contention duration to cause the contention events to be collected into crdb_internal.transaction_contention_events
sql.contention.txn_id_cache.max_size
byte size64 MiBthe maximum byte size TxnID cache will use (set to 0 to disable)
sql.cross_db_fks.enabled
booleanfalseif true, creating foreign key references across databases is allowed
sql.cross_db_sequence_owners.enabled
booleanfalseif true, creating sequences owned by tables from other databases is allowed
sql.cross_db_sequence_references.enabled
booleanfalseif true, sequences referenced by tables from other databases are allowed
sql.cross_db_views.enabled
booleanfalseif true, creating views that refer to other databases is allowed
sql.defaults.cost_scans_with_default_col_size.enabled
booleanfalsesetting to true uses the same size for all columns to compute scan cost
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.datestyle
enumerationiso, mdydefault value for DateStyle session setting [iso, mdy = 0, iso, dmy = 1, iso, ymd = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.default_hash_sharded_index_bucket_count
integer16used as bucket count if bucket count is not specified in hash sharded index definition
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.default_int_size
integer8the size, in bytes, of an INT type
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.disallow_full_table_scans.enabled
booleanfalsesetting to true rejects queries that have planned a full table scan
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.distsql
enumerationautodefault distributed SQL execution mode [off = 0, auto = 1, on = 2, always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.experimental_alter_column_type.enabled
booleanfalsedefault value for experimental_alter_column_type session setting; enables the use of ALTER COLUMN TYPE for general conversions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.experimental_distsql_planning
enumerationoffdefault experimental_distsql_planning mode; enables experimental opt-driven DistSQL planning [off = 0, on = 1]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.experimental_enable_unique_without_index_constraints.enabled
booleanfalsedefault value for experimental_enable_unique_without_index_constraints session setting;disables unique without index constraints by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.experimental_implicit_column_partitioning.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for the use of implicit column partitioning
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.experimental_temporary_tables.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for use of temporary tables by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.foreign_key_cascades_limit
integer10000default value for foreign_key_cascades_limit session setting; limits the number of cascading operations that run as part of a single query
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.idle_in_session_timeout
duration0sdefault value for the idle_in_session_timeout; default value for the idle_in_session_timeout session setting; controls the duration a session is permitted to idle before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.idle_in_transaction_session_timeout
duration0sdefault value for the idle_in_transaction_session_timeout; controls the duration a session is permitted to idle in a transaction before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.implicit_select_for_update.enabled
booleantruedefault value for enable_implicit_select_for_update session setting; enables FOR UPDATE locking during the row-fetch phase of mutation statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.insert_fast_path.enabled
booleantruedefault value for enable_insert_fast_path session setting; enables a specialized insert path
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.intervalstyle
enumerationpostgresdefault value for IntervalStyle session setting [postgres = 0, iso_8601 = 1, sql_standard = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.large_full_scan_rows
float1000default value for large_full_scan_rows session setting which determines the maximum table size allowed for a full scan when disallow_full_table_scans is set to true
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.locality_optimized_partitioned_index_scan.enabled
booleantruedefault value for locality_optimized_partitioned_index_scan session setting; enables searching for rows in the current region before searching remote regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.lock_timeout
duration0sdefault value for the lock_timeout; default value for the lock_timeout session setting; controls the duration a query is permitted to wait while attempting to acquire a lock on a key or while blocking on an existing lock in order to perform a non-locking read on a key; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.on_update_rehome_row.enabled
booleantruedefault value for on_update_rehome_row; enables ON UPDATE rehome_row() expressions to trigger on updates
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.optimizer_use_histograms.enabled
booleantruedefault value for optimizer_use_histograms session setting; enables usage of histograms in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.optimizer_use_multicol_stats.enabled
booleantruedefault value for optimizer_use_multicol_stats session setting; enables usage of multi-column stats in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.override_alter_primary_region_in_super_region.enabled
booleanfalsedefault value for override_alter_primary_region_in_super_region; allows for altering the primary region even if the primary region is a member of a super region
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.override_multi_region_zone_config.enabled
booleanfalsedefault value for override_multi_region_zone_config; allows for overriding the zone configs of a multi-region table or database
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.prefer_lookup_joins_for_fks.enabled
booleanfalsedefault value for prefer_lookup_joins_for_fks session setting; causes foreign key operations to use lookup joins when possible
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.primary_region
stringif not empty, all databases created without a PRIMARY REGION will implicitly have the given PRIMARY REGION
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.reorder_joins_limit
integer8default number of joins to reorder
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.require_explicit_primary_keys.enabled
booleanfalsedefault value for requiring explicit primary keys in CREATE TABLE statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.results_buffer.size
byte size16 KiBdefault size of the buffer that accumulates results for a statement or a batch of statements before they are sent to the client. This can be overridden on an individual connection with the 'results_buffer_size' parameter. Note that auto-retries generally only happen while no results have been delivered to the client, so reducing this size can increase the number of retriable errors a client receives. On the other hand, increasing the buffer size can increase the delay until the client receives the first result row. Updating the setting only affects new connections. Setting to 0 disables any buffering.
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.serial_normalization
enumerationrowiddefault handling of SERIAL in table definitions [rowid = 0, virtual_sequence = 1, sql_sequence = 2, sql_sequence_cached = 3, unordered_rowid = 4]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.statement_timeout
duration0sdefault value for the statement_timeout; default value for the statement_timeout session setting; controls the duration a query is permitted to run before it is canceled; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.stub_catalog_tables.enabled
booleantruedefault value for stub_catalog_tables session setting
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.super_regions.enabled
booleanfalsedefault value for enable_super_regions; allows for the usage of super regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.transaction_rows_read_err
integer0the limit for the number of rows read by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.transaction_rows_read_log
integer0the threshold for the number of rows read by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.transaction_rows_written_err
integer0the limit for the number of rows written by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.transaction_rows_written_log
integer0the threshold for the number of rows written by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.use_declarative_schema_changer
enumerationondefault value for use_declarative_schema_changer session setting;disables new schema changer by default [off = 0, on = 1, unsafe = 2, unsafe_always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.vectorize
enumerationondefault vectorize mode [on = 0, on = 2, experimental_always = 3, off = 4]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.defaults.zigzag_join.enabled
booleantruedefault value for enable_zigzag_join session setting; allows use of zig-zag join by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET
sql.distsql.temp_storage.workmem
byte size64 MiBmaximum amount of memory in bytes a processor can use before falling back to temp storage
sql.guardrails.max_row_size_err
byte size512 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an error is returned; use 0 to disable
sql.guardrails.max_row_size_log
byte size64 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an event is logged to SQL_PERF (or SQL_INTERNAL_PERF if the mutating statement was internal); use 0 to disable
sql.hash_sharded_range_pre_split.max
integer16max pre-split ranges to have when adding hash sharded index to an existing table
sql.insights.anomaly_detection.enabled
booleantrueenable per-fingerprint latency recording and anomaly detection
sql.insights.anomaly_detection.latency_threshold
duration50msstatements must surpass this threshold to trigger anomaly detection and identification
sql.insights.anomaly_detection.memory_limit
byte size1.0 MiBthe maximum amount of memory allowed for tracking statement latencies
sql.insights.execution_insights_capacity
integer1000the size of the per-node store of execution insights
sql.insights.high_retry_count.threshold
integer10the number of retries a slow statement must have undergone for its high retry count to be highlighted as a potential problem
sql.insights.latency_threshold
duration100msamount of time after which an executing statement is considered slow. Use 0 to disable.
sql.log.slow_query.experimental_full_table_scans.enabled
booleanfalsewhen set to true, statements that perform a full table/index scan will be logged to the slow query log even if they do not meet the latency threshold. Must have the slow query log enabled for this setting to have any effect.
sql.log.slow_query.internal_queries.enabled
booleanfalsewhen set to true, internal queries which exceed the slow query log threshold are logged to a separate log. Must have the slow query log enabled for this setting to have any effect.
sql.log.slow_query.latency_threshold
duration0swhen set to non-zero, log statements whose service latency exceeds the threshold to a secondary logger on each node
sql.log.user_audit
stringuser/role-based audit logging configuration. An enterprise license is required for this cluster setting to take effect.
sql.log.user_audit.reduced_config.enabled
booleanfalseenables logic to compute a reduced audit configuration, computing the audit configuration only once at session start instead of at each SQL event. The tradeoff with the increase in performance (~5%), is that changes to the audit configuration (user role memberships/cluster setting) are not reflected within session. Users will need to start a new session to see these changes in their auditing behaviour.
sql.metrics.index_usage_stats.enabled
booleantruecollect per index usage statistics
sql.metrics.max_mem_reported_stmt_fingerprints
integer100000the maximum number of reported statement fingerprints stored in memory
sql.metrics.max_mem_reported_txn_fingerprints
integer100000the maximum number of reported transaction fingerprints stored in memory
sql.metrics.max_mem_stmt_fingerprints
integer100000the maximum number of statement fingerprints stored in memory
sql.metrics.max_mem_txn_fingerprints
integer100000the maximum number of transaction fingerprints stored in memory
sql.metrics.statement_details.dump_to_logs
booleanfalsedump collected statement statistics to node logs when periodically cleared
sql.metrics.statement_details.enabled
booleantruecollect per-statement query statistics
sql.metrics.statement_details.gateway_node.enabled
booleantruesave the gateway node for each statement fingerprint. If false, the value will be stored as 0.
sql.metrics.statement_details.index_recommendation_collection.enabled
booleantruegenerate an index recommendation for each fingerprint ID
sql.metrics.statement_details.max_mem_reported_idx_recommendations
integer5000the maximum number of reported index recommendation info stored in memory
sql.metrics.statement_details.plan_collection.enabled
booleanfalseperiodically save a logical plan for each fingerprint
sql.metrics.statement_details.plan_collection.period
duration5m0sthe time until a new logical plan is collected
sql.metrics.statement_details.threshold
duration0sminimum execution time to cause statement statistics to be collected. If configured, no transaction stats are collected.
sql.metrics.transaction_details.enabled
booleantruecollect per-application transaction statistics
sql.multiple_modifications_of_table.enabled
booleanfalseif true, allow statements containing multiple INSERT ON CONFLICT, UPSERT, UPDATE, or DELETE subqueries modifying the same table, at the risk of data corruption if the same row is modified multiple times by a single statement (multiple INSERT subqueries without ON CONFLICT cannot cause corruption and are always allowed)
sql.multiregion.drop_primary_region.enabled
booleantrueallows dropping the PRIMARY REGION of a database if it is the last region
sql.notices.enabled
booleantrueenable notices in the server/client protocol being sent
sql.optimizer.uniqueness_checks_for_gen_random_uuid.enabled
booleanfalseif enabled, uniqueness checks may be planned for mutations of UUID columns updated with gen_random_uuid(); otherwise, uniqueness is assumed due to near-zero collision probability
sql.schema.telemetry.recurrence
string@weeklycron-tab recurrence for SQL schema telemetry job
sql.show_ranges_deprecated_behavior.enabled
booleantrueif set, SHOW RANGES and crdb_internal.ranges{_no_leases} behave with deprecated pre-v23.1 semantics. NB: the new SHOW RANGES interface has richer WITH options than pre-v23.1 SHOW RANGES.
sql.spatial.experimental_box2d_comparison_operators.enabled
booleanfalseenables the use of certain experimental box2d comparison operators
sql.stats.activity.persisted_rows.max
integer200000maximum number of rows of statement and transaction activity that will be persisted in the system tables
sql.stats.automatic_collection.enabled
booleantrueautomatic statistics collection mode
sql.stats.automatic_collection.fraction_stale_rows
float0.2target fraction of stale rows per table that will trigger a statistics refresh
sql.stats.automatic_collection.min_stale_rows
integer500target minimum number of stale rows per table that will trigger a statistics refresh
sql.stats.cleanup.recurrence
string@hourlycron-tab recurrence for SQL Stats cleanup job
sql.stats.flush.enabled
booleantrueif set, SQL execution statistics are periodically flushed to disk
sql.stats.flush.interval
duration10m0sthe interval at which SQL execution statistics are flushed to disk, this value must be less than or equal to 1 hour
sql.stats.forecasts.enabled
booleantruewhen true, enables generation of statistics forecasts by default for all tables
sql.stats.forecasts.max_decrease
float0the most a prediction is allowed to decrease, expressed as the minimum ratio of the prediction to the lowest prior observation
sql.stats.forecasts.min_goodness_of_fit
float0.95the minimum R² (goodness of fit) measurement required from all predictive models to use a forecast
sql.stats.forecasts.min_observations
integer3the mimimum number of observed statistics required to produce a statistics forecast
sql.stats.histogram_buckets.count
integer200maximum number of histogram buckets to build during table statistics collection
sql.stats.histogram_collection.enabled
booleantruehistogram collection mode
sql.stats.histogram_samples.count
integer10000number of rows sampled for histogram construction during table statistics collection
sql.stats.multi_column_collection.enabled
booleantruemulti-column statistics collection mode
sql.stats.non_default_columns.min_retention_period
duration24h0m0sminimum retention period for table statistics collected on non-default columns
sql.stats.persisted_rows.max
integer1000000maximum number of rows of statement and transaction statistics that will be persisted in the system tables before compaction begins
sql.stats.post_events.enabled
booleanfalseif set, an event is logged for every CREATE STATISTICS job
sql.stats.response.max
integer20000the maximum number of statements and transaction stats returned in a CombinedStatements request
sql.stats.response.show_internal.enabled
booleanfalsecontrols if statistics for internal executions should be returned by the CombinedStatements and if internal sessions should be returned by the ListSessions endpoints. These endpoints are used to display statistics on the SQL Activity pages
sql.stats.system_tables.enabled
booleantruewhen true, enables use of statistics on system tables by the query optimizer
sql.stats.system_tables_autostats.enabled
booleantruewhen true, enables automatic collection of statistics on system tables
sql.telemetry.query_sampling.enabled
booleanfalsewhen set to true, executed queries will emit an event on the telemetry logging channel
sql.telemetry.query_sampling.internal.enabled
booleanfalsewhen set to true, internal queries will be sampled in telemetry logging
sql.temp_object_cleaner.cleanup_interval
duration30m0show often to clean up orphaned temporary objects
sql.temp_object_cleaner.wait_interval
duration30m0show long after creation a temporary object will be cleaned up
sql.trace.log_statement_execute
booleanfalseset to true to enable logging of executed statements
sql.trace.session_eventlog.enabled
booleanfalseset to true to enable session tracing; note that enabling this may have a negative performance impact
sql.trace.stmt.enable_threshold
duration0senables tracing on all statements; statements executing for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting applies to individual statements within a transaction and is therefore finer-grained than sql.trace.txn.enable_threshold
sql.trace.txn.enable_threshold
duration0senables tracing on all transactions; transactions open for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting is coarser-grained than sql.trace.stmt.enable_threshold because it applies to all statements within a transaction as well as client communication (e.g. retries)
sql.ttl.default_delete_batch_size
integer100default amount of rows to delete in a single query during a TTL job
sql.ttl.default_delete_rate_limit
integer100default delete rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.
sql.ttl.default_select_batch_size
integer500default amount of rows to select in a single query during a TTL job
sql.ttl.job.enabled
booleantruewhether the TTL job is enabled
sql.txn_fingerprint_id_cache.capacity
integer100the maximum number of txn fingerprint IDs stored
storage.max_sync_duration
duration20smaximum duration for disk operations; any operations that take longer than this setting trigger a warning log entry or process crash
storage.max_sync_duration.fatal.enabled
booleantrueif true, fatal the process when a disk operation exceeds storage.max_sync_duration
storage.value_blocks.enabled
booleantrueset to true to enable writing of value blocks in sstables
timeseries.storage.enabled
booleantrueif set, periodic timeseries data is stored within the cluster; disabling is not recommended unless you are storing the data elsewhere
timeseries.storage.resolution_10s.ttl
duration240h0m0sthe maximum age of time series data stored at the 10 second resolution. Data older than this is subject to rollup and deletion.
timeseries.storage.resolution_30m.ttl
duration2160h0m0sthe maximum age of time series data stored at the 30 minute resolution. Data older than this is subject to deletion.
trace.debug.enable
booleanfalseif set, traces for recent requests can be seen at https://<ui>/debug/requests
trace.jaeger.agent
stringthe address of a Jaeger agent to receive traces using the Jaeger UDP Thrift protocol, as <host>:<port>. If no port is specified, 6381 will be used.
trace.opentelemetry.collector
stringaddress of an OpenTelemetry trace collector to receive traces using the otel gRPC protocol, as <host>:<port>. If no port is specified, 4317 will be used.
trace.snapshot.rate
duration0sif non-zero, interval at which background trace snapshots are captured
trace.span_registry.enabled
booleantrueif set, ongoing traces can be seen at https://<ui>/#/debug/tracez
trace.zipkin.collector
stringthe address of a Zipkin instance to receive traces, as <host>:<port>. If no port is specified, 9411 will be used.
version
version23.1set the active cluster version in the format '<major>.<minor>'
diff --git a/src/current/_includes/cockroach-generated/release-23.1/sql/aggregates.md b/src/current/_includes/cockroach-generated/release-23.1/sql/aggregates.md new file mode 100644 index 00000000000..3488d264159 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-23.1/sql/aggregates.md @@ -0,0 +1,519 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_agg(arg1: bool) → bool[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes) → bytes[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date) → date[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal) → decimal[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float) → float[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet) → inet[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int) → int[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval) → interval[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string) → string[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time) → time[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp) → timestamp[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz) → timestamptz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid) → uuid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum) → anyenum[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d) → box2d[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography) → geography[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry) → geometry[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb) → jsonb[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid) → oid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz) → timetz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple) → tuple[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit) → varbit[]

Aggregates the selected values into an array.

+		Immutable
array_cat_agg(arg1: bool[]) → bool[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: bytes[]) → bytes[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: date[]) → date[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: decimal[]) → decimal[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: float[]) → float[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: inet[]) → inet[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: int[]) → int[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: interval[]) → interval[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: string[]) → string[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: time[]) → time[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamp[]) → timestamp[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamptz[]) → timestamptz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: uuid[]) → uuid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: anyenum[]) → anyenum[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: box2d[]) → box2d[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geography[]) → geography[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geometry[]) → geometry[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: jsonb[]) → jsonb[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: oid[]) → oid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timetz[]) → timetz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: tuple[]) → tuple[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: varbit[]) → varbit[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
avg(arg1: decimal) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: float) → float

Calculates the average of the selected values.

+		Immutable
avg(arg1: int) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: interval) → interval

Calculates the average of the selected values.

+		Immutable
bit_and(arg1: int) → int

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_and(arg1: varbit) → varbit

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: int) → int

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: varbit) → varbit

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bool_and(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
bool_or(arg1: bool) → bool

Calculates the boolean value of ORing all selected values.

+		Immutable
concat_agg(arg1: bytes) → bytes

Concatenates all selected values.

+		Immutable
concat_agg(arg1: string) → string

Concatenates all selected values.

+		Immutable
corr(arg1: decimal, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
count(arg1: anyelement) → int

Calculates the number of selected elements.

+		Immutable
count_rows() → int

Calculates the number of rows.

+		Immutable
covar_pop(arg1: decimal, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
every(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
json_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
json_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
jsonb_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
jsonb_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
max(arg1: bool) → bool

Identifies the maximum selected value.

+		Immutable
max(arg1: bytes) → bytes

Identifies the maximum selected value.

+		Immutable
max(arg1: date) → date

Identifies the maximum selected value.

+		Immutable
max(arg1: decimal) → decimal

Identifies the maximum selected value.

+		Immutable
max(arg1: float) → float

Identifies the maximum selected value.

+		Immutable
max(arg1: inet) → inet

Identifies the maximum selected value.

+		Immutable
max(arg1: int) → int

Identifies the maximum selected value.

+		Immutable
max(arg1: interval) → interval

Identifies the maximum selected value.

+		Immutable
max(arg1: string) → string

Identifies the maximum selected value.

+		Immutable
max(arg1: time) → time

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamp) → timestamp

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamptz) → timestamptz

Identifies the maximum selected value.

+		Immutable
max(arg1: uuid) → uuid

Identifies the maximum selected value.

+		Immutable
max(arg1: anyenum) → anyenum

Identifies the maximum selected value.

+		Immutable
max(arg1: box2d) → box2d

Identifies the maximum selected value.

+		Immutable
max(arg1: collatedstring{*}) → collatedstring{*}

Identifies the maximum selected value.

+		Immutable
max(arg1: geography) → geography

Identifies the maximum selected value.

+		Immutable
max(arg1: geometry) → geometry

Identifies the maximum selected value.

+		Immutable
max(arg1: jsonb) → jsonb

Identifies the maximum selected value.

+		Immutable
max(arg1: oid) → oid

Identifies the maximum selected value.

+		Immutable
max(arg1: timetz) → timetz

Identifies the maximum selected value.

+		Immutable
max(arg1: varbit) → varbit

Identifies the maximum selected value.

+		Immutable
min(arg1: bool) → bool

Identifies the minimum selected value.

+		Immutable
min(arg1: bytes) → bytes

Identifies the minimum selected value.

+		Immutable
min(arg1: date) → date

Identifies the minimum selected value.

+		Immutable
min(arg1: decimal) → decimal

Identifies the minimum selected value.

+		Immutable
min(arg1: float) → float

Identifies the minimum selected value.

+		Immutable
min(arg1: inet) → inet

Identifies the minimum selected value.

+		Immutable
min(arg1: int) → int

Identifies the minimum selected value.

+		Immutable
min(arg1: interval) → interval

Identifies the minimum selected value.

+		Immutable
min(arg1: string) → string

Identifies the minimum selected value.

+		Immutable
min(arg1: time) → time

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamp) → timestamp

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamptz) → timestamptz

Identifies the minimum selected value.

+		Immutable
min(arg1: uuid) → uuid

Identifies the minimum selected value.

+		Immutable
min(arg1: anyenum) → anyenum

Identifies the minimum selected value.

+		Immutable
min(arg1: box2d) → box2d

Identifies the minimum selected value.

+		Immutable
min(arg1: collatedstring{*}) → collatedstring{*}

Identifies the minimum selected value.

+		Immutable
min(arg1: geography) → geography

Identifies the minimum selected value.

+		Immutable
min(arg1: geometry) → geometry

Identifies the minimum selected value.

+		Immutable
min(arg1: jsonb) → jsonb

Identifies the minimum selected value.

+		Immutable
min(arg1: oid) → oid

Identifies the minimum selected value.

+		Immutable
min(arg1: timetz) → timetz

Identifies the minimum selected value.

+		Immutable
min(arg1: varbit) → varbit

Identifies the minimum selected value.

+		Immutable
percentile_cont(arg1: float) → float

Continuous percentile: returns a float corresponding to the specified fraction in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float) → interval

Continuous percentile: returns an interval corresponding to the specified fraction in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_cont(arg1: float[]) → float[]

Continuous percentile: returns floats corresponding to the specified fractions in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float[]) → interval[]

Continuous percentile: returns intervals corresponding to the specified fractions in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_disc(arg1: float) → anyelement

Discrete percentile: returns the first input value whose position in the ordering equals or exceeds the specified fraction.

+		Immutable
percentile_disc(arg1: float[]) → anyelement

Discrete percentile: returns input values whose position in the ordering equals or exceeds the specified fractions.

+		Immutable
regr_avgx(arg1: decimal, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_count(arg1: decimal, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_intercept(arg1: decimal, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_r2(arg1: decimal, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_slope(arg1: decimal, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_sxx(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
sqrdiff(arg1: decimal) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: float) → float

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: int) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
st_collect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_extent(arg1: geometry) → box2d

Forms a Box2D that encapsulates all provided geometries.

+		Immutable
st_makeline(arg1: geometry) → geometry

Forms a LineString from Point, MultiPoint or LineStrings. Other shapes will be ignored.

+		Immutable
st_memcollect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_memunion(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
st_union(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
stddev(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: decimal) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: float) → float

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: int) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
string_agg(arg1: bytes, arg2: bytes) → bytes

Concatenates all selected values using the provided delimiter.

+		Immutable
string_agg(arg1: string, arg2: string) → string

Concatenates all selected values using the provided delimiter.

+		Immutable
sum(arg1: decimal) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: float) → float

Calculates the sum of the selected values.

+		Immutable
sum(arg1: int) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: interval) → interval

Calculates the sum of the selected values.

+		Immutable
sum_int(arg1: int) → int

Calculates the sum of the selected values.

+		Immutable
var_pop(arg1: decimal) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: float) → float

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: int) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_samp(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
variance(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
xor_agg(arg1: bytes) → bytes

Calculates the bitwise XOR of the selected values.

+		Immutable
xor_agg(arg1: int) → int

Calculates the bitwise XOR of the selected values.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-23.1/sql/functions.md b/src/current/_includes/cockroach-generated/release-23.1/sql/functions.md new file mode 100644 index 00000000000..16f11b043c3 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-23.1/sql/functions.md @@ -0,0 +1,3623 @@ +### Array functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_append(array: bool[], elem: bool) → bool[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: bytes[], elem: bytes) → bytes[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: date[], elem: date) → date[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: decimal[], elem: decimal) → decimal[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: float[], elem: float) → float[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: inet[], elem: inet) → inet[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: int[], elem: int) → int[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: interval[], elem: interval) → interval[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: string[], elem: string) → string[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: time[], elem: time) → time[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamp[], elem: timestamp) → timestamp[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamptz[], elem: timestamptz) → timestamptz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: uuid[], elem: uuid) → uuid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: anyenum[], elem: anyenum) → anyenum[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: box2d[], elem: box2d) → box2d[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geography[], elem: geography) → geography[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geometry[], elem: geometry) → geometry[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: jsonb[], elem: jsonb) → jsonb[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: oid[], elem: oid) → oid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timetz[], elem: timetz) → timetz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: tuple[], elem: tuple) → tuple[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: varbit[], elem: varbit) → varbit[]

Appends elem to array, returning the result.

+		Immutable
array_cat(left: bool[], right: bool[]) → bool[]

Appends two arrays.

+		Immutable
array_cat(left: bytes[], right: bytes[]) → bytes[]

Appends two arrays.

+		Immutable
array_cat(left: date[], right: date[]) → date[]

Appends two arrays.

+		Immutable
array_cat(left: decimal[], right: decimal[]) → decimal[]

Appends two arrays.

+		Immutable
array_cat(left: float[], right: float[]) → float[]

Appends two arrays.

+		Immutable
array_cat(left: inet[], right: inet[]) → inet[]

Appends two arrays.

+		Immutable
array_cat(left: int[], right: int[]) → int[]

Appends two arrays.

+		Immutable
array_cat(left: interval[], right: interval[]) → interval[]

Appends two arrays.

+		Immutable
array_cat(left: string[], right: string[]) → string[]

Appends two arrays.

+		Immutable
array_cat(left: time[], right: time[]) → time[]

Appends two arrays.

+		Immutable
array_cat(left: timestamp[], right: timestamp[]) → timestamp[]

Appends two arrays.

+		Immutable
array_cat(left: timestamptz[], right: timestamptz[]) → timestamptz[]

Appends two arrays.

+		Immutable
array_cat(left: uuid[], right: uuid[]) → uuid[]

Appends two arrays.

+		Immutable
array_cat(left: anyenum[], right: anyenum[]) → anyenum[]

Appends two arrays.

+		Immutable
array_cat(left: box2d[], right: box2d[]) → box2d[]

Appends two arrays.

+		Immutable
array_cat(left: geography[], right: geography[]) → geography[]

Appends two arrays.

+		Immutable
array_cat(left: geometry[], right: geometry[]) → geometry[]

Appends two arrays.

+		Immutable
array_cat(left: jsonb[], right: jsonb[]) → jsonb[]

Appends two arrays.

+		Immutable
array_cat(left: oid[], right: oid[]) → oid[]

Appends two arrays.

+		Immutable
array_cat(left: timetz[], right: timetz[]) → timetz[]

Appends two arrays.

+		Immutable
array_cat(left: tuple[], right: tuple[]) → tuple[]

Appends two arrays.

+		Immutable
array_cat(left: varbit[], right: varbit[]) → varbit[]

Appends two arrays.

+		Immutable
array_length(input: anyelement[], array_dimension: int) → int

Calculates the length of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_lower(input: anyelement[], array_dimension: int) → int

Calculates the minimum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_position(array: bool[], elem: bool) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bytes[], elem: bytes) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: date[], elem: date) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: decimal[], elem: decimal) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: float[], elem: float) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: inet[], elem: inet) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: int[], elem: int) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: interval[], elem: interval) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: string[], elem: string) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: time[], elem: time) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamp[], elem: timestamp) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: uuid[], elem: uuid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: anyenum[], elem: anyenum) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: box2d[], elem: box2d) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geography[], elem: geography) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geometry[], elem: geometry) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: jsonb[], elem: jsonb) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: oid[], elem: oid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timetz[], elem: timetz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: tuple[], elem: tuple) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: varbit[], elem: varbit) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_positions(array: bool[], elem: bool) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: bytes[], elem: bytes) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: date[], elem: date) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: decimal[], elem: decimal) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: float[], elem: float) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: inet[], elem: inet) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: int[], elem: int) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: interval[], elem: interval) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: string[], elem: string) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: time[], elem: time) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamp[], elem: timestamp) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamptz[], elem: timestamptz) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: uuid[], elem: uuid) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: anyenum[], elem: anyenum) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: box2d[], elem: box2d) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geography[], elem: geography) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geometry[], elem: geometry) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: jsonb[], elem: jsonb) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: oid[], elem: oid) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timetz[], elem: timetz) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: tuple[], elem: tuple) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: varbit[], elem: varbit) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_prepend(elem: bool, array: bool[]) → bool[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: bytes, array: bytes[]) → bytes[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: date, array: date[]) → date[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: decimal, array: decimal[]) → decimal[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: float, array: float[]) → float[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: inet, array: inet[]) → inet[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: int, array: int[]) → int[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: interval, array: interval[]) → interval[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: string, array: string[]) → string[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: time, array: time[]) → time[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamp, array: timestamp[]) → timestamp[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamptz, array: timestamptz[]) → timestamptz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: uuid, array: uuid[]) → uuid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: anyenum, array: anyenum[]) → anyenum[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: box2d, array: box2d[]) → box2d[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geography, array: geography[]) → geography[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geometry, array: geometry[]) → geometry[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: jsonb, array: jsonb[]) → jsonb[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: oid, array: oid[]) → oid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timetz, array: timetz[]) → timetz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: tuple, array: tuple[]) → tuple[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: varbit, array: varbit[]) → varbit[]

Prepends elem to array, returning the result.

+		Immutable
array_remove(array: bool[], elem: bool) → bool[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: bytes[], elem: bytes) → bytes[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: date[], elem: date) → date[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: decimal[], elem: decimal) → decimal[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: float[], elem: float) → float[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: inet[], elem: inet) → inet[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: int[], elem: int) → int[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: interval[], elem: interval) → interval[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: string[], elem: string) → string[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: time[], elem: time) → time[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamp[], elem: timestamp) → timestamp[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamptz[], elem: timestamptz) → timestamptz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: uuid[], elem: uuid) → uuid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: anyenum[], elem: anyenum) → anyenum[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: box2d[], elem: box2d) → box2d[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geography[], elem: geography) → geography[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geometry[], elem: geometry) → geometry[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: jsonb[], elem: jsonb) → jsonb[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: oid[], elem: oid) → oid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timetz[], elem: timetz) → timetz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: tuple[], elem: tuple) → tuple[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: varbit[], elem: varbit) → varbit[]

Remove from array all elements equal to elem.

+		Immutable
array_replace(array: bool[], toreplace: bool, replacewith: bool) → bool[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: bytes[], toreplace: bytes, replacewith: bytes) → bytes[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: date[], toreplace: date, replacewith: date) → date[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: decimal[], toreplace: decimal, replacewith: decimal) → decimal[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: float[], toreplace: float, replacewith: float) → float[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: inet[], toreplace: inet, replacewith: inet) → inet[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: int[], toreplace: int, replacewith: int) → int[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: interval[], toreplace: interval, replacewith: interval) → interval[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: string[], toreplace: string, replacewith: string) → string[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: time[], toreplace: time, replacewith: time) → time[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamp[], toreplace: timestamp, replacewith: timestamp) → timestamp[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamptz[], toreplace: timestamptz, replacewith: timestamptz) → timestamptz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: uuid[], toreplace: uuid, replacewith: uuid) → uuid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: anyenum[], toreplace: anyenum, replacewith: anyenum) → anyenum[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: box2d[], toreplace: box2d, replacewith: box2d) → box2d[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geography[], toreplace: geography, replacewith: geography) → geography[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geometry[], toreplace: geometry, replacewith: geometry) → geometry[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: jsonb[], toreplace: jsonb, replacewith: jsonb) → jsonb[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: oid[], toreplace: oid, replacewith: oid) → oid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timetz[], toreplace: timetz, replacewith: timetz) → timetz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: tuple[], toreplace: tuple, replacewith: tuple) → tuple[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: varbit[], toreplace: varbit, replacewith: varbit) → varbit[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_to_string(input: anyelement[], delim: string) → string

Join an array into a string with a delimiter.

+		Stable
array_to_string(input: anyelement[], delimiter: string, null: string) → string

Join an array into a string with a delimiter, replacing NULLs with a null string.

+		Stable
array_upper(input: anyelement[], array_dimension: int) → int

Calculates the maximum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
cardinality(input: anyelement[]) → int

Calculates the number of elements contained in input

+		Immutable
crdb_internal.merge_aggregated_stmt_metadata(input: jsonb[]) → jsonb

Merge an array of AggregatedStatementMetadata into a single JSONB object

+		Immutable
crdb_internal.merge_statement_stats(input: jsonb[]) → jsonb

Merge an array of appstatspb.StatementStatistics into a single JSONB object

+		Immutable
crdb_internal.merge_stats_metadata(input: jsonb[]) → jsonb

Merge an array of StmtStatsMetadata into a single JSONB object

+		Immutable
crdb_internal.merge_transaction_stats(input: jsonb[]) → jsonb

Merge an array of appstatspb.TransactionStatistics into a single JSONB object

+		Immutable
jsonb_array_to_string_array(input: jsonb) → string[]

Convert a JSONB array into a string array.

+		Immutable
string_to_array(str: string, delimiter: string) → string[]

Split a string into components on a delimiter.

+		Immutable
string_to_array(str: string, delimiter: string, null: string) → string[]

Split a string into components on a delimiter with a specified string to consider NULL.

+		Immutable
+ +### BOOL functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Matches case insensetively unescaped with pattern using escape as an escape token.

+		Immutable
inet_contained_by_or_equals(val: inet, container: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_contains_or_equals(container: inet, val: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_same_family(val: inet, val: inet) → bool

Checks if two IP addresses are of the same IP family.

+		Immutable
like_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
not_ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches case insensetively with pattern using escape as an escape token.

+		Immutable
not_like_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
not_similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
+ +### Comparison functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
greatest(anyelement...) → anyelement

Returns the element with the greatest value.

+		Immutable
least(anyelement...) → anyelement

Returns the element with the lowest value.

+		Immutable
num_nonnulls(anyelement...) → int

Returns the number of nonnull arguments.

+		Immutable
num_nulls(anyelement...) → int

Returns the number of null arguments.

+		Immutable
+ +### Cryptographic functions + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crypt(password: string, salt: string) → string

Generates a hash based on a password and salt. The hash algorithm and number of rounds if applicable are encoded in the salt.

+		Immutable
digest(data: bytes, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
digest(data: string, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
gen_salt(type: string) → string

Generates a salt for input into the crypt function using the default number of rounds.

+		Volatile
gen_salt(type: string, iter_count: int) → string

Generates a salt for input into the crypt function using iter_count number of rounds.

+		Volatile
hmac(data: bytes, key: bytes, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
hmac(data: string, key: string, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
+ +### DECIMAL functions + + + + + +
Function → ReturnsDescriptionVolatility
hlc_to_timestamp(hlc: decimal) → timestamptz

Returns a TimestampTZ representation of a CockroachDB HLC in decimal form.

+

Note that a TimestampTZ has less precision than a CockroachDB HLC. It is intended as +a convenience function to display HLCs in a print-friendly form. Use the decimal +value if you rely on the HLC for accuracy.

+		Immutable
+ +### Date and time functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
age(end: timestamptz, begin: timestamptz) → interval

Calculates the interval between begin and end, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use the timestamptz subtraction operator.

+		Immutable
age(val: timestamptz) → interval

Calculates the interval between val and the current time, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use now() - timestamptz.

+		Stable
clock_timestamp() → timestamp

Returns the current system time on one of the cluster nodes.

+		Volatile
clock_timestamp() → timestamptz

Returns the current system time on one of the cluster nodes.

+		Volatile
current_date() → date

Returns the date of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_timestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
date_part(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
date_part(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
date_trunc(element: string, input: date) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: interval) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: time) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero.

+

Compatible elements: hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamp) → timestamp

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamptz) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: timestamptz, timezone: string) → timestamptz

Truncates input to precision element in the specified timezone. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
experimental_follower_read_timestamp() → timestamptz

Same as follower_read_timestamp. This name is deprecated.

+		Volatile
experimental_strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
extract(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
extract(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
extract_duration(element: string, input: interval) → int

Extracts element from input. +Compatible elements: hour, minute, second, millisecond, microsecond. +This is deprecated in favor of extract which supports duration.

+		Immutable
follower_read_timestamp() → timestamptz

Returns a timestamp which is very likely to be safe to perform +against a follower replica.

+

This function is intended to be used with an AS OF SYSTEM TIME clause to perform +historical reads against a time which is recent but sufficiently old for reads +to be performed against the closest replica as opposed to the currently +leaseholder for a given range.

+

Note that this function requires an enterprise license on a CCL distribution to +return a result that is less likely the closest replica. It is otherwise +hardcoded as -4.8s from the statement time, which may not result in reading from the +nearest replica.

+		Volatile
localtimestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
make_date(year: int, month: int, day: int) → date

Create date (formatted according to ISO 8601) from year, month, and day fields (negative years signify BC).

+		Immutable
make_timestamp(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamp

Create timestamp (formatted according to ISO 8601) from year, month, day, hour, minute, and seconds fields (negative years signify BC).

+		Immutable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float, timezone: string) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
now() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
overlaps(s1: date, e1: date, s1: date, e2: date) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: date, e1: interval, s1: date, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: interval, s1: time, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: time, s1: time, e2: time) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: interval, s1: timestamp, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: timestamp, s1: timestamp, e2: timestamp) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamptz, e1: interval, s1: timestamptz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Stable
overlaps(s1: timestamptz, e1: timestamptz, s1: timestamptz, e2: timestamptz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: interval, s1: timetz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: timetz, s1: timetz, e2: timetz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
statement_timestamp() → timestamp

Returns the start time of the current statement.

+		Stable
statement_timestamp() → timestamptz

Returns the start time of the current statement.

+		Stable
strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
timeofday() → string

Returns the current system time on one of the cluster nodes as a string.

+		Stable
timezone(timezone: string, time: time) → timetz

Treat given time without time zone as located in the specified time zone.

+		Stable
timezone(timezone: string, timestamp: timestamp) → timestamptz

Treat given time stamp without time zone as located in the specified time zone.

+		Immutable
timezone(timezone: string, timestamptz: timestamptz) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Immutable
timezone(timezone: string, timestamptz_string: string) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Stable
timezone(timezone: string, timetz: timetz) → timetz

Convert given time with time zone to the new time zone.

+		Stable
to_char(date: date) → string

Convert an date to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(date: date, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_char(interval: interval) → string

Convert an interval to a string assuming the Postgres IntervalStyle.

+		Immutable
to_char(interval: interval, format: string) → string

Convert an interval to a string using the given format.

+		Stable
to_char(timestamp: timestamp) → string

Convert an timestamp to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(timestamp: timestamp, format: string) → string

Convert an timestamp to a string using the given format.

+		Stable
to_char(timestamptz: timestamptz, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_timestamp(timestamp: float) → timestamptz

Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to timestamp with time zone.

+		Immutable
transaction_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
with_max_staleness(max_staleness: interval) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_max_staleness(max_staleness: interval, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
+ +### Enum functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
enum_first(val: anyenum) → anyenum

Returns the first value of the input enum type.

+		Stable
enum_last(val: anyenum) → anyenum

Returns the last value of the input enum type.

+		Stable
enum_range(lower: anyenum, upper: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array between the two arguments (inclusive).

+		Stable
enum_range(val: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array.

+		Stable
+ +### FLOAT functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abs(val: decimal) → decimal

Calculates the absolute value of val.

+		Immutable
abs(val: float) → float

Calculates the absolute value of val.

+		Immutable
abs(val: int) → int

Calculates the absolute value of val.

+		Immutable
acos(val: float) → float

Calculates the inverse cosine of val.

+		Immutable
acosd(val: float) → float

Calculates the inverse cosine of val with the result in degrees

+		Immutable
acosh(val: float) → float

Calculates the inverse hyperbolic cosine of val.

+		Immutable
asin(val: float) → float

Calculates the inverse sine of val.

+		Immutable
asind(val: float) → float

Calculates the inverse sine of val with the result in degrees.

+		Immutable
asinh(val: float) → float

Calculates the inverse hyperbolic sine of val.

+		Immutable
atan(val: float) → float

Calculates the inverse tangent of val.

+		Immutable
atan2(x: float, y: float) → float

Calculates the inverse tangent of x/y.

+		Immutable
atan2d(x: float, y: float) → float

Calculates the inverse tangent of x/y with the result in degrees

+		Immutable
atand(val: float) → float

Calculates the inverse tangent of val with the result in degrees.

+		Immutable
atanh(val: float) → float

Calculates the inverse hyperbolic tangent of val.

+		Immutable
cbrt(val: decimal) → decimal

Calculates the cube root (∛) of val.

+		Immutable
cbrt(val: float) → float

Calculates the cube root (∛) of val.

+		Immutable
ceil(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
cos(val: float) → float

Calculates the cosine of val.

+		Immutable
cosd(val: float) → float

Calculates the cosine of val where val is in degrees.

+		Immutable
cosh(val: float) → float

Calculates the hyperbolic cosine of val.

+		Immutable
cot(val: float) → float

Calculates the cotangent of val.

+		Immutable
cotd(val: float) → float

Calculates the cotangent of val where val is in degrees.

+		Immutable
degrees(val: float) → float

Converts val as a radian value to a degree value.

+		Immutable
div(x: decimal, y: decimal) → decimal

Calculates the integer quotient of x/y.

+		Immutable
div(x: float, y: float) → float

Calculates the integer quotient of x/y.

+		Immutable
div(x: int, y: int) → int

Calculates the integer quotient of x/y.

+		Immutable
exp(val: decimal) → decimal

Calculates e ^ val.

+		Immutable
exp(val: float) → float

Calculates e ^ val.

+		Immutable
floor(val: decimal) → decimal

Calculates the largest integer not greater than val.

+		Immutable
floor(val: float) → float

Calculates the largest integer not greater than val.

+		Immutable
floor(val: int) → float

Calculates the largest integer not greater than val.

+		Immutable
isnan(val: decimal) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
isnan(val: float) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
ln(val: decimal) → decimal

Calculates the natural log of val.

+		Immutable
ln(val: float) → float

Calculates the natural log of val.

+		Immutable
log(b: decimal, x: decimal) → decimal

Calculates the base b log of val.

+		Immutable
log(b: float, x: float) → float

Calculates the base b log of val.

+		Immutable
log(val: decimal) → decimal

Calculates the base 10 log of val.

+		Immutable
log(val: float) → float

Calculates the base 10 log of val.

+		Immutable
mod(x: decimal, y: decimal) → decimal

Calculates x%y.

+		Immutable
mod(x: float, y: float) → float

Calculates x%y.

+		Immutable
mod(x: int, y: int) → int

Calculates x%y.

+		Immutable
pi() → float

Returns the value for pi (3.141592653589793).

+		Immutable
pow(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
pow(x: float, y: float) → float

Calculates x^y.

+		Immutable
pow(x: int, y: int) → int

Calculates x^y.

+		Immutable
power(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
power(x: float, y: float) → float

Calculates x^y.

+		Immutable
power(x: int, y: int) → int

Calculates x^y.

+		Immutable
radians(val: float) → float

Converts val as a degree value to a radians value.

+		Immutable
random() → float

Returns a random floating-point number between 0 (inclusive) and 1 (exclusive). Note that the value contains at most 53 bits of randomness.

+		Volatile
round(input: decimal, decimal_accuracy: int) → decimal

Keeps decimal_accuracy number of figures to the right of the zero position in input using half away from zero rounding. If decimal_accuracy is not in the range -2^31…(2^31-1), the results are undefined.

+		Immutable
round(input: float, decimal_accuracy: int) → float

Keeps decimal_accuracy number of figures to the right of the zero position in input using half to even (banker’s) rounding.

+		Immutable
round(val: decimal) → decimal

Rounds val to the nearest integer, half away from zero: round(+/-2.4) = +/-2, round(+/-2.5) = +/-3.

+		Immutable
round(val: float) → float

Rounds val to the nearest integer using half to even (banker’s) rounding.

+		Immutable
sign(val: decimal) → decimal

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: float) → float

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: int) → int

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sin(val: float) → float

Calculates the sine of val.

+		Immutable
sind(val: float) → float

Calculates the sine of val where val is in degrees.

+		Immutable
sinh(val: float) → float

Calculates the hyperbolic sine of val.

+		Immutable
sqrt(val: decimal) → decimal

Calculates the square root of val.

+		Immutable
sqrt(val: float) → float

Calculates the square root of val.

+		Immutable
tan(val: float) → float

Calculates the tangent of val.

+		Immutable
tand(val: float) → float

Calculates the tangent of val where val is in degrees.

+		Immutable
tanh(val: float) → float

Calculates the hyperbolic tangent of val.

+		Immutable
trunc(val: decimal) → decimal

Truncates the decimal values of val.

+		Immutable
trunc(val: decimal, scale: int) → decimal

Truncate val to scale decimal places

+		Immutable
trunc(val: float) → float

Truncates the decimal values of val.

+		Immutable
+ +### Full Text Search functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
phraseto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The <-> operator is inserted between each token in the input.

+		Immutable
phraseto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The <-> operator is inserted between each token in the input.

+		Stable
plainto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The & operator is inserted between each token in the input.

+		Immutable
plainto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The & operator is inserted between each token in the input.

+		Stable
to_tsquery(config: string, text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the specified configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Immutable
to_tsquery(text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the default configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Stable
to_tsvector(config: string, text: string) → tsvector

Converts text to a tsvector, normalizing words according to the specified configuration. Position information is included in the result.

+		Immutable
to_tsvector(text: string) → tsvector

Converts text to a tsvector, normalizing words according to the default configuration. Position information is included in the result.

+		Stable
ts_parse(parser_name: string, document: string) → tuple{int AS tokid, string AS token}

ts_parse parses the given document and returns a series of records, one for each token produced by parsing. Each record includes a tokid showing the assigned token type and a token which is the text of the token.

+		Stable
ts_rank(vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
+ +### Fuzzy String Matching functions + + + + + + + +
Function → ReturnsDescriptionVolatility
levenshtein(source: string, target: string) → int

Calculates the Levenshtein distance between two strings. Maximum input length is 255 characters.

+		Immutable
levenshtein(source: string, target: string, ins_cost: int, del_cost: int, sub_cost: int) → int

Calculates the Levenshtein distance between two strings. The cost parameters specify how much to charge for each edit operation. Maximum input length is 255 characters.

+		Immutable
soundex(source: string) → string

Convert a string to its Soundex code.

+		Immutable
+ +### ID generation functions + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
experimental_uuid_v4() → bytes

Returns a UUID.

+		Volatile
gen_random_ulid() → uuid

Generates a random ULID and returns it as a value of UUID type.

+		Volatile
gen_random_uuid() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
unique_rowid() → int

Returns a unique ID used by CockroachDB to generate unique row IDs if a Primary Key isn’t defined for the table. The value is a combination of the insert timestamp and the ID of the node executing the statement, which guarantees this combination is globally unique. However, there can be gaps and the order is not completely guaranteed.

+		Volatile
unordered_unique_rowid() → int

Returns a unique ID. The value is a combination of the insert timestamp and the ID of the node executing the statement, which guarantees this combination is globally unique. The way it is generated there is no ordering

+		Volatile
uuid_generate_v1() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. To avoid exposing the server’s real MAC address, this uses a random MAC address and a timestamp. Essentially, this is an alias for uuid_generate_v1mc.

+		Volatile
uuid_generate_v1mc() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. This uses a random MAC address and a timestamp.

+		Volatile
uuid_generate_v3(namespace: uuid, name: string) → uuid

Generates a version 3 UUID in the given namespace using the specified input name, with md5 as the hashing method. The namespace should be one of the special constants produced by the uuid_ns_*() functions.

+		Immutable
uuid_generate_v4() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
uuid_generate_v5(namespace: uuid, name: string) → uuid

Generates a version 5 UUID in the given namespace using the specified input name. This is similar to a version 3 UUID, except it uses SHA-1 for hashing.

+		Immutable
uuid_nil() → uuid

Returns a nil UUID constant.

+		Immutable
uuid_ns_dns() → uuid

Returns a constant designating the DNS namespace for UUIDs.

+		Immutable
uuid_ns_oid() → uuid

Returns a constant designating the ISO object identifier (OID) namespace for UUIDs. These are unrelated to the OID type used internally in the database.

+		Immutable
uuid_ns_url() → uuid

Returns a constant designating the URL namespace for UUIDs.

+		Immutable
uuid_ns_x500() → uuid

Returns a constant designating the X.500 distinguished name (DN) namespace for UUIDs.

+		Immutable
uuid_v4() → bytes

Returns a UUID.

+		Volatile
+ +### INET functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abbrev(val: inet) → string

Converts the combined IP address and prefix length to an abbreviated display format as text.For INET types, this will omit the prefix length if it’s not the default (32 or IPv4, 128 for IPv6)

+

For example, abbrev('192.168.1.2/24') returns '192.168.1.2/24'

+		Immutable
broadcast(val: inet) → inet

Gets the broadcast address for the network address represented by the value.

+

For example, broadcast('192.168.1.2/24') returns '192.168.1.255/24'

+		Immutable
family(val: inet) → int

Extracts the IP family of the value; 4 for IPv4, 6 for IPv6.

+

For example, family('::1') returns 6

+		Immutable
host(val: inet) → string

Extracts the address part of the combined address/prefixlen value as text.

+

For example, host('192.168.1.2/16') returns '192.168.1.2'

+		Immutable
hostmask(val: inet) → inet

Creates an IP host mask corresponding to the prefix length in the value.

+

For example, hostmask('192.168.1.2/16') returns '0.0.255.255'

+		Immutable
masklen(val: inet) → int

Retrieves the prefix length stored in the value.

+

For example, masklen('192.168.1.2/16') returns 16

+		Immutable
netmask(val: inet) → inet

Creates an IP network mask corresponding to the prefix length in the value.

+

For example, netmask('192.168.1.2/16') returns '255.255.0.0'

+		Immutable
set_masklen(val: inet, prefixlen: int) → inet

Sets the prefix length of val to prefixlen.

+

For example, set_masklen('192.168.1.2', 16) returns '192.168.1.2/16'.

+		Immutable
+ +### INT functions + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crc32c(bytes...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32c(string...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32ieee(bytes...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
crc32ieee(string...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
fnv32(bytes...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32(string...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32a(bytes...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv32a(string...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64(bytes...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64(string...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64a(bytes...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64a(string...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
width_bucket(operand: decimal, b1: decimal, b2: decimal, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2.

+		Immutable
width_bucket(operand: int, b1: int, b2: int, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2.

+		Immutable
width_bucket(operand: anyelement, thresholds: anyelement[]) → int

return the bucket number to which operand would be assigned given an array listing the lower bounds of the buckets; returns 0 for an input less than the first lower bound; the thresholds array must be sorted, smallest first, or unexpected results will be obtained

+		Immutable
+ +### JSONB functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_to_json(array: anyelement[]) → jsonb

Returns the array as JSON or JSONB.

+		Stable
array_to_json(array: anyelement[], pretty_bool: bool) → jsonb

Returns the array as JSON or JSONB.

+		Stable
crdb_internal.job_payload_type(data: bytes) → string

Reads the type from the jobspb.Payload protocol message.

+		Immutable
crdb_internal.json_to_pb(pbname: string, json: jsonb) → bytes

Convert JSONB data to protocol message bytes

+		Immutable
crdb_internal.pb_to_json(pbname: string, data: bytes) → jsonb

Converts protocol message to its JSONB representation.

+		Immutable
crdb_internal.pb_to_json(pbname: string, data: bytes, emit_defaults: bool) → jsonb

Converts protocol message to its JSONB representation.

+		Immutable
crdb_internal.pb_to_json(pbname: string, data: bytes, emit_defaults: bool, emit_redacted: bool) → jsonb

Converts protocol message to its JSONB representation.

+		Immutable
json_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
json_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
json_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
json_build_array(anyelement...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
json_build_object(anyelement...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
json_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
json_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
json_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
json_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
json_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
json_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
json_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
json_remove_path(val: jsonb, path: string[]) → jsonb

Remove the specified path from the JSON object.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
json_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
json_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
json_valid(string: string) → bool

Returns whether the given string is a valid JSON or not

+		Immutable
jsonb_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
jsonb_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
jsonb_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
jsonb_build_array(anyelement...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
jsonb_build_object(anyelement...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
jsonb_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
jsonb_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
jsonb_exists_any(json: jsonb, array: string[]) → bool

Returns whether any of the strings in the text array exist as top-level keys or array elements

+		Immutable
jsonb_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments. new_val will be inserted before path target.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb, insert_after: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If insert_after is true (default is false), new_val will be inserted after path target.

+		Immutable
jsonb_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
jsonb_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
jsonb_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
jsonb_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
jsonb_pretty(val: jsonb) → string

Returns the given JSON value as a STRING indented and with newlines.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
jsonb_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
jsonb_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
row_to_json(row: tuple) → jsonb

Returns the row as a JSON object.

+		Stable
to_json(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
to_jsonb(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
+ +### Multi-region functions + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crdb_internal.filter_multiregion_fields_from_zone_config_sql(val: string) → string

Takes in a CONFIGURE ZONE SQL statement and returns a modified +SQL statement omitting multi-region related zone configuration fields. +If the CONFIGURE ZONE statement can be inferred by the database’s or +table’s zone configuration this will return NULL.

+		Stable
crdb_internal.reset_multi_region_zone_configs_for_database(id: int) → bool

Resets the zone configuration for a multi-region database to +match its original state. No-ops if the given database ID is not multi-region +enabled.

+		Volatile
crdb_internal.reset_multi_region_zone_configs_for_table(id: int) → bool

Resets the zone configuration for a multi-region table to +match its original state. No-ops if the given table ID is not a multi-region +table.

+		Volatile
crdb_internal.validate_multi_region_zone_configs() → bool

Validates all multi-region zone configurations are correctly setup +for the current database, including all tables, indexes and partitions underneath. +Returns an error if validation fails. This builtin uses un-leased versions of the +each descriptor, requiring extra round trips.

+		Volatile
default_to_database_primary_region(val: string) → string

Returns the given region if the region has been added to the current database. +Otherwise, this will return the primary region of the current database. +This will error if the current database is not a multi-region database.

+		Stable
gateway_region() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
rehome_row() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
+ +### STRING[] functions + + + + + + +
Function → ReturnsDescriptionVolatility
regexp_split_to_array(string: string, pattern: string) → string[]

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_array(string: string, pattern: string, flags: string) → string[]

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
+ +### Sequence functions + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
currval(sequence_name: string) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
currval(sequence_name: regclass) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
lastval() → int

Return value most recently obtained with nextval in this session.

+		Volatile
nextval(sequence_name: string) → int

Advances the given sequence and returns its new value.

+		Volatile
nextval(sequence_name: regclass) → int

Advances the given sequence and returns its new value.

+		Volatile
setval(sequence_name: string, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: string, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
setval(sequence_name: regclass, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: regclass, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
+ +### Set-returning functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
aclexplode(aclitems: string[]) → tuple{oid AS grantor, oid AS grantee, string AS privilege_type, bool AS is_grantable}

Produces a virtual table containing aclitem stuff (returns no rows as this feature is unsupported in CockroachDB)

+		Stable
crdb_internal.scan(span: bytes[]) → tuple{bytes AS key, bytes AS value, string AS ts}

Returns the raw keys and values from the specified span

+		Stable
crdb_internal.scan(start_key: bytes, end_key: bytes) → tuple{bytes AS key, bytes AS value, string AS ts}

Returns the raw keys and values with their timestamp from the specified span

+		Stable
crdb_internal.tenant_span_stats() → tuple{int AS database_id, int AS table_id, int AS range_count, int AS approximate_disk_bytes, int AS live_bytes, int AS total_bytes, float AS live_percentage}

Returns statistics (range count, disk size, live range bytes, total range bytes, live range byte percentage) for all of the tenant’s tables.

+		Stable
crdb_internal.tenant_span_stats(database_id: int) → tuple{int AS database_id, int AS table_id, int AS range_count, int AS approximate_disk_bytes, int AS live_bytes, int AS total_bytes, float AS live_percentage}

Returns statistics (range count, disk size, live range bytes, total range bytes, live range byte percentage) for tables of the provided database id.

+		Stable
crdb_internal.tenant_span_stats(database_id: int, table_id: int) → tuple{int AS database_id, int AS table_id, int AS range_count, int AS approximate_disk_bytes, int AS live_bytes, int AS total_bytes, float AS live_percentage}

Returns statistics (range count, disk size, live range bytes, total range bytes, live range byte percentage) for the provided table id.

+		Stable
crdb_internal.testing_callback(name: string) → int

For internal CRDB testing only. The function calls a callback identified by name registered with the server by the test.

+		Volatile
crdb_internal.unary_table() → tuple

Produces a virtual table containing a single row with no values.

+

This function is used only by CockroachDB’s developers for testing purposes.

+		Volatile
generate_series(start: int, end: int) → int

Produces a virtual table containing the integer values from start to end, inclusive.

+		Immutable
generate_series(start: int, end: int, step: int) → int

Produces a virtual table containing the integer values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamp, end: timestamp, step: interval) → timestamp

Produces a virtual table containing the timestamp values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamptz, end: timestamptz, step: interval) → timestamptz

Produces a virtual table containing the timestampTZ values from start to end, inclusive, by increment of step.

+		Immutable
generate_subscripts(array: anyelement[]) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int, reverse: bool) → int

Returns a series comprising the given array’s subscripts.

+

When reverse is true, the series is returned in reverse order.

+		Immutable
information_schema._pg_expandarray(input: anyelement[]) → tuple{anyelement AS x, int AS n}

Returns the input array as a set of rows with an index

+		Immutable
json_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
json_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
json_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
jsonb_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
jsonb_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
jsonb_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
pg_get_keywords() → tuple{string AS word, string AS catcode, string AS catdesc}

Produces a virtual table containing the keywords known to the SQL parser.

+		Immutable
pg_options_to_table(options: string[]) → tuple{string AS option_name, string AS option_value}

Converts the options array format to a table.

+		Stable
regexp_split_to_table(string: string, pattern: string) → string

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_table(string: string, pattern: string, flags: string) → string

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
unnest(anyelement[], anyelement[], anyelement[]...) → tuple{anyelement AS unnest, anyelement AS unnest, anyelement AS unnest}

Returns the input arrays as a set of rows

+		Immutable
unnest(input: anyelement[]) → anyelement

Returns the input array as a set of rows

+		Immutable
+ +### Spatial functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
_st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
geometrytype(geometry: geometry) → string

Returns the type of geometry as a string.

+

This function utilizes the GEOS module.

+		Immutable
geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
postgis_addbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_dropbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_extensions_upgrade() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_full_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_geos_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_getbbox(geometry: geometry) → box2d

Returns a box2d encapsulating the given Geometry.

+		Immutable
postgis_hasbbox(geometry: geometry) → bool

Returns whether a given Geometry has a bounding box. False for points and empty geometries; always true otherwise.

+		Immutable
postgis_lib_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_lib_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_liblwgeom_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_libxml_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_proj_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_installed() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_released() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_wagyu_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
st_addmeasure(geometry: geometry, start: float, end: float) → geometry

Returns a copy of a LineString or MultiLineString with measure coordinates linearly interpolated between the specified start and end values. Any existing M coordinates will be overwritten.

+		Immutable
st_addpoint(line_string: geometry, point: geometry) → geometry

Adds a Point to the end of a LineString.

+		Immutable
st_addpoint(line_string: geometry, point: geometry, index: int) → geometry

Adds a Point to a LineString at the given 0-based index (-1 to append).

+		Immutable
st_affine(geometry: geometry, a: float, b: float, c: float, d: float, e: float, f: float, g: float, h: float, i: float, x_off: float, y_off: float, z_off: float) → geometry

Applies a 3D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b c x_off \ / x
+| d e f y_off | | y | +| g h i z_off | | z | +\ 0 0 0 1 / \ 0 /

+		Immutable
st_affine(geometry: geometry, a: float, b: float, d: float, e: float, x_off: float, y_off: float) → geometry

Applies a 2D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b x_off \ / x
+| d e y_off | | y | +\ 0 0 1 / \ 0 /

+		Immutable
st_angle(line1: geometry, line2: geometry) → float

Returns the clockwise angle between two LINESTRING geometries, treating them as vectors between their start- and endpoints. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry) → float

Returns the clockwise angle between the vectors formed by point2,point1 and point2,point3. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry, point4: geometry) → float

Returns the clockwise angle between the vectors formed by point1,point2 and point3,point4. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_area(geography: geography) → float

Returns the area of the given geography in meters^2. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geography: geography, use_spheroid: bool) → float

Returns the area of the given geography in meters^2.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_area(geometry_str: string) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_area2d(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_asbinary(geography: geography) → bytes

Returns the WKB representation of a given Geography.

+		Immutable
st_asbinary(geography: geography, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asbinary(geometry: geometry) → bytes

Returns the WKB representation of a given Geometry.

+		Immutable
st_asbinary(geometry: geometry, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asencodedpolyline(geometry: geometry) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Preserves 5 decimal places.

+		Immutable
st_asencodedpolyline(geometry: geometry, precision: int4) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+		Immutable
st_asewkb(geography: geography) → bytes

Returns the EWKB representation of a given Geography.

+		Immutable
st_asewkb(geometry: geometry) → bytes

Returns the EWKB representation of a given Geometry.

+		Immutable
st_asewkt(geography: geography) → string

Returns the EWKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_asewkt(geography: geography, max_decimal_digits: int) → string

Returns the EWKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry: geometry) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_asewkt(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry_str: string) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asewkt(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geography: geography) → string

Returns the GeoJSON representation of a given Geography. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option (default for Geography)
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326
    • +
+		Immutable
st_asgeojson(geometry: geometry) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+		Immutable
st_asgeojson(geometry_str: string) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(row: tuple) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(row: tuple, geo_column: string) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. Coordinates have a maximum of 9 decimal digits.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int, pretty: bool) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value. Output will be pretty printed in JSON if pretty is true.

+		Stable
st_ashexewkb(geography: geography) → string

Returns the EWKB representation in hex of a given Geography.

+		Immutable
st_ashexewkb(geography: geography, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexewkb(geometry: geometry) → string

Returns the EWKB representation in hex of a given Geometry.

+		Immutable
st_ashexewkb(geometry: geometry, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexwkb(geography: geography) → string

Returns the WKB representation in hex of a given Geography.

+		Immutable
st_ashexwkb(geometry: geometry) → string

Returns the WKB representation in hex of a given Geometry.

+		Immutable
st_askml(geography: geography) → string

Returns the KML representation of a given Geography.

+		Immutable
st_askml(geometry: geometry) → string

Returns the KML representation of a given Geometry.

+		Immutable
st_askml(geometry_str: string) → string

Returns the KML representation of a given Geometry.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astext(geography: geography) → string

Returns the WKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_astext(geography: geography, max_decimal_digits: int) → string

Returns the WKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry: geometry) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_astext(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry_str: string) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astext(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int, precision_m: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_azimuth(geography_a: geography, geography_b: geography) → float

Returns the azimuth in radians of the segment defined by the given point geographies, or NULL if the two points are coincident. It is solved using the Inverse geodesic problem.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_azimuth(geometry_a: geometry, geometry_b: geometry) → float

Returns the azimuth in radians of the segment defined by the given point geometries, or NULL if the two points are coincident.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+		Immutable
st_boundary(geometry: geometry) → geometry

Returns the closure of the combinatorial boundary of this Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_box2dfromgeohash(geohash: string) → box2d

Return a Box2D from a GeoHash string with max precision.

+		Immutable
st_box2dfromgeohash(geohash: string, precision: int) → box2d

Return a Box2D from a GeoHash string with supplied precision.

+		Immutable
st_buffer(geography: geography, distance: float) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, buffer_style_params: string) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, quad_segs: int) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geometry: geometry, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry_str: string, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_centroid(geography: geography) → geography

Returns the centroid of given geography. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geography: geography, use_spheroid: bool) → geography

Returns the centroid of given geography.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geometry: geometry) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_centroid(geometry_str: string) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_clipbybox2d(geometry: geometry, box2d: box2d) → geometry

Clips the geometry to conform to the bounding box specified by box2d.

+		Immutable
st_closestpoint(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the 2-dimensional point on geometry_a that is closest to geometry_b. This is the first point of the shortest line.

+		Immutable
st_collectionextract(geometry: geometry, type: int) → geometry

Given a collection, returns a multitype consisting only of elements of the specified type. If there are no elements of the given type, an EMPTY geometry is returned. Types are specified as 1=POINT, 2=LINESTRING, 3=POLYGON - other types are not supported.

+		Immutable
st_collectionhomogenize(geometry: geometry) → geometry

Returns the “simplest” representation of a collection’s contents. Collections of a single type will be returned as an appopriate multitype, or a singleton if it only contains a single geometry.

+		Immutable
st_combinebbox(box2d: box2d, geometry: geometry) → box2d

Combines the current bounding box with the bounding box of the Geometry.

+		Immutable
st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_convexhull(geometry: geometry) → geometry

Returns a geometry that represents the Convex Hull of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_coorddim(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_difference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the difference of two Geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_dimension(geometry: geometry) → int

Returns the number of topological dimensions of a given Geometry.

+		Immutable
st_disjoint(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a does not overlap, touch or is within geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_distance(geography_a: geography, geography_b: geography) → float

Returns the distance in meters between geography_a and geography_b. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geography_a: geography, geography_b: geography, use_spheroid: bool) → float

Returns the distance in meters between geography_a and geography_b.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance between the given geometries.

+		Immutable
st_distance(geometry_a_str: string, geometry_b_str: string) → float

Returns the distance between the given geometries.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_distancesphere(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_distancespheroid(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a spheroid.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_endpoint(geometry: geometry) → geometry

Returns the last point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_envelope(box2d: box2d) → geometry

Returns a bounding geometry for the given box.

+		Immutable
st_envelope(geometry: geometry) → geometry

Returns a bounding envelope for the given geometry.

+

For geometries which have a POINT or LINESTRING bounding box (i.e. is a single point +or a horizontal or vertical line), a POINT or LINESTRING is returned. Otherwise, the +returned POLYGON will be ordered Bottom Left, Top Left, Top Right, Bottom Right, +Bottom Left.

+		Immutable
st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string, parent_only: bool) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+

The parent_only boolean is always ignored.

+		Stable
st_estimatedextent(table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_expand(box2d: box2d, delta: float) → box2d

Extends the box2d by delta units across all dimensions.

+		Immutable
st_expand(box2d: box2d, delta_x: float, delta_y: float) → box2d

Extends the box2d by delta_x units in the x dimension and delta_y units in the y dimension.

+		Immutable
st_expand(geometry: geometry, delta: float) → geometry

Extends the bounding box represented by the geometry by delta units across all dimensions, returning a Polygon representing the new bounding box.

+		Immutable
st_expand(geometry: geometry, delta_x: float, delta_y: float) → geometry

Extends the bounding box represented by the geometry by delta_x units in the x dimension and delta_y units in the y dimension, returning a Polygon representing the new bounding box.

+		Immutable
st_exteriorring(geometry: geometry) → geometry

Returns the exterior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon.

+		Immutable
st_flipcoordinates(geometry: geometry) → geometry

Returns a new geometry with the X and Y axes flipped.

+		Immutable
st_force2d(geometry: geometry) → geometry

Returns a Geometry that is forced into XY layout with any Z or M dimensions discarded.

+		Immutable
st_force3d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to 0. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry, defaultM: float) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to the specified default M value. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force4d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZM layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float, defaultM: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified Z value. If a M coordinate doesn’t exist, it will be set to the specified M value.

+		Immutable
st_forcecollection(geometry: geometry) → geometry

Converts the geometry into a GeometryCollection.

+		Immutable
st_forcepolygonccw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_forcepolygoncw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Frechet distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Frechet distance between the given geometries, with the given segment densification (range 0.0-1.0, -1 to disable).

+

Smaller densify_frac gives a more accurate Fréchet distance. However, the computation time and memory usage increases with the square of the number of subsegments.

+

This function utilizes the GEOS module.

+		Immutable
st_generatepoints(geometry: geometry, npoints: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. Uses system time as a seed. +The requested number of points must be not larger than 65336.

+		Volatile
st_generatepoints(geometry: geometry, npoints: int4, seed: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. +The requested number of points must be not larger than 65336.

+		Immutable
st_geogfromewkb(val: bytes) → geography

Returns the Geography from an EWKB representation.

+		Immutable
st_geogfromewkt(val: string) → geography

Returns the Geography from an EWKT representation.

+		Immutable
st_geogfromgeojson(val: string) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromgeojson(val: jsonb) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geogfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geogfromwkb(bytes: bytes, srid: int) → geography

Returns the Geography from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geogfromwkb(val: bytes) → geography

Returns the Geography from a WKB (or EWKB) representation.

+		Immutable
st_geographyfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geographyfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geohash(geography: geography) → string

Returns a GeoHash representation of the geeographywith full precision if a point is provided, or with variable precision based on the size of the feature.

+		Immutable
st_geohash(geography: geography, precision: int) → string

Returns a GeoHash representation of the geography with the supplied precision.

+		Immutable
st_geohash(geometry: geometry) → string

Returns a GeoHash representation of the geometry with full precision if a point is provided, or with variable precision based on the size of the feature. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geohash(geometry: geometry, precision: int) → string

Returns a GeoHash representation of the geometry with the supplied precision. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geomcollfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomcollfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geometryfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geometryfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geometryn(geometry: geometry, n: int) → geometry

Returns the n-th Geometry (1-indexed). Returns NULL if out of bounds.

+		Immutable
st_geometrytype(geometry: geometry) → string

Returns the type of geometry as a string prefixed with ST_.

+

This function utilizes the GEOS module.

+		Immutable
st_geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
st_geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
st_geomfromgeohash(geohash: string) → geometry

Return a POLYGON Geometry from a GeoHash string with max precision.

+		Immutable
st_geomfromgeohash(geohash: string, precision: int) → geometry

Return a POLYGON Geometry from a GeoHash string with supplied precision.

+		Immutable
st_geomfromgeojson(val: string) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromgeojson(val: jsonb) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geomfromwkb(bytes: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geomfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_hasarc(geometry: geometry) → bool

Returns whether there is a CIRCULARSTRING in the geometry.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Hausdorff distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Hausdorff distance between the given geometries, with the given segment densification (range 0.0-1.0).

+

This function utilizes the GEOS module.

+		Immutable
st_interiorringn(geometry: geometry, n: int) → geometry

Returns the n-th (1-indexed) interior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon, or the ring does not exist.

+		Immutable
st_intersection(geography_a: geography, geography_b: geography) → geography

Returns the point intersections of the given geographies.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a_str: string, geometry_b_str: string) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_isclosed(geometry: geometry) → bool

Returns whether the geometry is closed as defined by whether the start and end points are coincident. Points are considered closed, empty geometries are not. For collections and multi-types, all members must be closed, as must all polygon rings.

+		Immutable
st_iscollection(geometry: geometry) → bool

Returns whether the geometry is of a collection type (including multi-types).

+		Immutable
st_isempty(geometry: geometry) → bool

Returns whether the geometry is empty.

+		Immutable
st_ispolygonccw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are considered counter-clockwise.

+		Immutable
st_ispolygoncw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are considered clockwise.

+		Immutable
st_isring(geometry: geometry) → bool

Returns whether the geometry is a single linestring that is closed and simple, as defined by ST_IsClosed and ST_IsSimple.

+

This function utilizes the GEOS module.

+		Immutable
st_issimple(geometry: geometry) → bool

Returns true if the geometry has no anomalous geometric points, e.g. that it intersects with or lies tangent to itself.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry) → bool

Returns whether the geometry is valid as defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry, flags: int) → bool

Returns whether the geometry is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry) → string

Returns a string containing the reason the geometry is invalid along with the point of interest, or “Valid Geometry” if it is valid. Validity is defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry, flags: int) → string

Returns the reason the geometry is invalid or “Valid Geometry” if it is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidtrajectory(geometry: geometry) → bool

Returns whether the geometry encodes a valid trajectory.

+

Note the geometry must be a LineString with M coordinates.

+		Immutable
st_length(geography: geography) → float

Returns the length of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geography: geography, use_spheroid: bool) → float

Returns the length of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_length(geometry_str: string) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_length2d(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_linecrossingdirection(linestring_a: geometry, linestring_b: geometry) → int

Returns an interger value defining behavior of crossing of lines: +0: lines do not cross, +-1: linestring_b crosses linestring_a from right to left, +1: linestring_b crosses linestring_a from left to right, +-2: linestring_b crosses linestring_a multiple times from right to left, +2: linestring_b crosses linestring_a multiple times from left to right, +-3: linestring_b crosses linestring_a multiple times from left to left, +3: linestring_b crosses linestring_a multiple times from right to right.

+

Note that the top vertex of the segment touching another line does not count as a crossing, but the bottom vertex of segment touching another line is considered a crossing.

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string) → geometry

Creates a LineString from an Encoded Polyline string.

+

Returns valid results only if the polyline was encoded with 5 decimal places.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string, precision: int4) → geometry

Creates a LineString from an Encoded Polyline string.

+

Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefrommultipoint(geometry: geometry) → geometry

Creates a LineString from a MultiPoint geometry.

+		Immutable
st_linefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_lineinterpolatepoint(geometry: geometry, fraction: float) → geometry

Returns a point along the given LineString which is at given fraction of LineString’s total length.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float, repeat: bool) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length. If repeat is false (default true) then it returns first point.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_linelocatepoint(line: geometry, point: geometry) → float

Returns a float between 0 and 1 representing the location of the closest point on LineString to the given Point, as a fraction of total 2d line length.

+		Immutable
st_linemerge(geometry: geometry) → geometry

Returns a LineString or MultiLineString by joining together constituents of a MultiLineString with matching endpoints. If the input is not a MultiLineString or LineString, an empty GeometryCollection is returned.

+

This function utilizes the GEOS module.

+		Immutable
st_linestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: decimal, end_fraction: decimal) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: float, end_fraction: float) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_longestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the max distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the maximum distance between the geometry’s vertexes. The function will return the longest line that was discovered first when comparing maximum distances if more than one is found.

+		Immutable
st_m(geometry: geometry) → float

Returns the M coordinate of a geometry if it is a Point.

+		Immutable
st_makebox2d(geometry_a: geometry, geometry_b: geometry) → box2d

Creates a box2d from two points. Errors if arguments are not two non-empty points.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with SRID 0.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float, srid: int) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with the given SRID.

+		Immutable
st_makepoint(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float) → geometry

Returns a new Point with the given X, Y, and Z coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float, m: float) → geometry

Returns a new Point with the given X, Y, Z, and M coordinates.

+		Immutable
st_makepointm(x: float, y: float, m: float) → geometry

Returns a new Point with the given X, Y, and M coordinates.

+		Immutable
st_makepolygon(geometry: geometry) → geometry

Returns a new Polygon with the given outer LineString.

+		Immutable
st_makepolygon(outer: geometry, interior: anyelement[]) → geometry

Returns a new Polygon with the given outer LineString and interior (hole) LineString(s).

+		Immutable
st_makevalid(geometry: geometry) → geometry

Returns a valid form of the given geometry according to the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_maxdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the maximum distance across every pair of points comprising the given geometries. Note if the geometries are the same, it will return the maximum distance between the geometry’s vertexes.

+		Immutable
st_memsize(geometry: geometry) → int

Returns the amount of memory space (in bytes) the geometry takes.

+		Immutable
st_minimumboundingcircle(geometry: geometry) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingcircle(geometry: geometry, num_segs: int) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingradius(geometry: geometry) → tuple{geometry AS center, float AS radius}

Returns a record containing the center point and radius of the smallest circle that can fully contains the given geometry.

+		Immutable
st_minimumclearance(geometry: geometry) → float

Returns the minimum distance a vertex can move before producing an invalid geometry. Returns Infinity if no minimum clearance can be found (e.g. for a single point).

+		Immutable
st_minimumclearanceline(geometry: geometry) → geometry

Returns a LINESTRING spanning the minimum distance a vertex can move before producing an invalid geometry. If no minimum clearance can be found (e.g. for a single point), an empty LINESTRING is returned.

+		Immutable
st_mlinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mlinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mpointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multi(geometry: geometry) → geometry

Returns the geometry as a new multi-geometry, e.g converts a POINT to a MULTIPOINT. If the input is already a multitype or collection, it is returned as is.

+		Immutable
st_multilinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multipointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_ndims(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_node(geometry: geometry) → geometry

Adds a node on a geometry for each intersection. Resulting geometry is always a MultiLineString.

+		Immutable
st_normalize(geometry: geometry) → geometry

Returns the geometry in its normalized form.

+

This function utilizes the GEOS module.

+		Immutable
st_npoints(geometry: geometry) → int

Returns the number of points in a given Geometry. Works for any shape type.

+		Immutable
st_nrings(geometry: geometry) → int

Returns the number of rings in a Polygon Geometry. Returns 0 if the shape is not a Polygon.

+		Immutable
st_numgeometries(geometry: geometry) → int

Returns the number of shapes inside a given Geometry.

+		Immutable
st_numinteriorring(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numinteriorrings(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numpoints(geometry: geometry) → int

Returns the number of points in a LineString. Returns NULL if the Geometry is not a LineString.

+		Immutable
st_orderingequals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is exactly equal to geometry_b, having all coordinates in the same order, as well as the same type, SRID, bounding box, and so on.

+		Immutable
st_orientedenvelope(geometry: geometry) → geometry

Returns a minimum rotated rectangle enclosing a geometry. +Note that more than one minimum rotated rectangle may exist. +May return a Point or LineString in the case of degenerate inputs.

+		Immutable
st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_perimeter(geography: geography) → float

Returns the perimeter of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geography: geography, use_spheroid: bool) → float

Returns the perimeter of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_perimeter2d(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_point(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_pointfromgeohash(geohash: string) → geometry

Return a POINT Geometry from a GeoHash string with max precision.

+		Immutable
st_pointfromgeohash(geohash: string, precision: int) → geometry

Return a POINT Geometry from a GeoHash string with supplied precision.

+		Immutable
st_pointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Point, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_pointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointinsidecircle(geometry: geometry, x_coord: float, y_coord: float, radius: float) → bool

Returns the true if the geometry is a point and is inside the circle. Returns false otherwise.

+		Immutable
st_pointn(geometry: geometry, n: int) → geometry

Returns the n-th Point of a LineString (1-indexed). Returns NULL if out of bounds or not a LineString.

+		Immutable
st_pointonsurface(geometry: geometry) → geometry

Returns a point that intersects with the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_points(geometry: geometry) → geometry

Returns all coordinates in the given Geometry as a MultiPoint, including duplicates.

+		Immutable
st_polyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygon(geometry: geometry, srid: int) → geometry

Returns a new Polygon from the given LineString and sets its SRID. It is equivalent to ST_MakePolygon with a single argument followed by ST_SetSRID.

+		Immutable
st_polygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_project(geography: geography, distance: float, azimuth: float) → geography

Returns a point projected from a start point along a geodesic using a given distance and azimuth (bearing). +This is known as the direct geodesic problem.

+

The distance is given in meters. Negative values are supported.

+

The azimuth (also known as heading or bearing) is given in radians. It is measured clockwise from true north (azimuth zero). +East is azimuth π/2 (90 degrees); south is azimuth π (180 degrees); west is azimuth 3π/2 (270 degrees). +Negative azimuth values and values greater than 2π (360 degrees) are supported.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, bnr: int) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b using the given boundary node rule (1:OGC/MOD2, 2:Endpoint, 3:MultivalentEndpoint, 4:MonovalentEndpoint).

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, pattern: string) → bool

Returns whether the DE-9IM spatial relation between geometry_a and geometry_b matches the DE-9IM pattern.

+

This function utilizes the GEOS module.

+		Immutable
st_relatematch(intersection_matrix: string, pattern: string) → bool

Returns whether the given DE-9IM intersection matrix satisfies the given pattern.

+		Immutable
st_removepoint(line_string: geometry, index: int) → geometry

Removes the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_removerepeatedpoints(geometry: geometry) → geometry

Returns a geometry with repeated points removed.

+		Immutable
st_removerepeatedpoints(geometry: geometry, tolerance: float) → geometry

Returns a geometry with repeated points removed, within the given distance tolerance.

+		Immutable
st_reverse(geometry: geometry) → geometry

Returns a modified geometry by reversing the order of its vertices.

+		Immutable
st_rotate(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_point: geometry) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_x: float, origin_y: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotatex(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the x axis by a rotation angle.

+		Immutable
st_rotatey(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the y axis by a rotation angle.

+		Immutable
st_rotatez(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the z axis by a rotation angle.

+		Immutable
st_s2covering(geography: geography) → geography

Returns a geography which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geography: geography, settings: string) → geography

Returns a geography which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geography, 's2_max_level=15,s2_level_mod=3').

+		Immutable
st_s2covering(geometry: geometry) → geometry

Returns a geometry which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geometry: geometry, settings: string) → geometry

Returns a geometry which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geometry, 's2_max_level=15,s2_level_mod=3')

+		Immutable
st_scale(g: geometry, factor: geometry) → geometry

Returns a modified Geometry scaled by taking in a Geometry as the factor.

+		Immutable
st_scale(g: geometry, factor: geometry, origin: geometry) → geometry

Returns a modified Geometry scaled by the Geometry factor relative to a false origin.

+		Immutable
st_scale(geometry: geometry, x_factor: float, y_factor: float) → geometry

Returns a modified Geometry scaled by the given factors.

+		Immutable
st_segmentize(geography: geography, max_segment_length_meters: float) → geography

Returns a modified Geography having no segment longer than the given max_segment_length meters.

+

The calculations are done on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_segmentize(geometry: geometry, max_segment_length: float) → geometry

Returns a modified Geometry having no segment longer than the given max_segment_length. Length units are in units of spatial reference.

+		Immutable
st_setpoint(line_string: geometry, index: int, point: geometry) → geometry

Sets the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_setsrid(geography: geography, srid: int) → geography

Sets a Geography to a new SRID without transforming the coordinates.

+		Immutable
st_setsrid(geometry: geometry, srid: int) → geometry

Sets a Geometry to a new SRID without transforming the coordinates.

+		Immutable
st_sharedpaths(geometry_a: geometry, geometry_b: geometry) → geometry

Returns a collection containing paths shared by the two input geometries.

+

Those going in the same direction are in the first element of the collection, +those going in the opposite direction are in the second element. +The paths themselves are given in the direction of the first geometry.

+		Immutable
st_shiftlongitude(geometry: geometry) → geometry

Returns a modified version of a geometry in which the longitude (X coordinate) of each point is incremented by 360 if it is <0 and decremented by 360 if it is >180. The result is only meaningful if the coordinates are in longitude/latitude.

+		Immutable
st_shortestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the minimum distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the minimum distance between the geometry’s vertexes. The function will return the shortest line that was discovered first when comparing minimum distances if more than one is found.

+		Immutable
st_simplify(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm.

+

This function utilizes the GEOS module.

+		Immutable
st_simplify(geometry: geometry, tolerance: float, preserve_collapsed: bool) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, retaining objects that would be too small given the tolerance if preserve_collapsed is set to true.

+		Immutable
st_simplifypreservetopology(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, avoiding the creation of invalid geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_snap(input: geometry, target: geometry, tolerance: float) → geometry

Snaps the vertices and segments of input geometry the target geometry’s vertices. +Tolerance is used to control where snapping is performed. The result geometry is the input geometry with the vertices snapped. +If no snapping occurs then the input geometry is returned unchanged.

+		Immutable
st_snaptogrid(geometry: geometry, origin: geometry, size_x: float, size_y: float, size_z: float, size_m: float) → geometry

Snap a geometry to a grid defined by the given origin and X, Y, Z, and M cell sizes. Any dimension with a 0 cell size will not be snapped.

+		Immutable
st_snaptogrid(geometry: geometry, origin_x: float, origin_y: float, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y based on an origin of (origin_x, origin_y).

+		Immutable
st_snaptogrid(geometry: geometry, size: float) → geometry

Snap a geometry to a grid of the given size. The specified size is only used to snap X and Y coordinates.

+		Immutable
st_snaptogrid(geometry: geometry, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y.

+		Immutable
st_srid(geography: geography) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geography as defined in spatial_ref_sys table.

+		Immutable
st_srid(geometry: geometry) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geometry as defined in spatial_ref_sys table.

+		Immutable
st_startpoint(geometry: geometry) → geometry

Returns the first point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_subdivide(geometry: geometry) → geometry

Returns a geometry divided into parts, where each part contains no more than 256 vertices.

+		Immutable
st_subdivide(geometry: geometry, max_vertices: int4) → geometry

Returns a geometry divided into parts, where each part contains no more than the number of vertices provided.

+		Immutable
st_summary(geography: geography) → string

Returns a text summary of the contents of the geography.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_summary(geometry: geometry) → string

Returns a text summary of the contents of the geometry.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_swapordinates(geometry: geometry, swap_ordinate_string: string) → geometry

Returns a version of the given geometry with given ordinates swapped. +The swap_ordinate_string parameter is a 2-character string naming the ordinates to swap. Valid names are: x, y, z and m.

+		Immutable
st_symdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_symmetricdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, srid: int) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates. The supplied SRID is set on the new geometry.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, srid: int) → geometry

Transforms a geometry into the given SRID coordinate reference system by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system referenced by the projection text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float, delta_z: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_transscale(geometry: geometry, delta_x: float, delta_y: float, x_factor: float, y_factor: float) → geometry

Translates the geometry using the deltaX and deltaY args, then scales it using the XFactor, YFactor args, working in 2D only.

+		Immutable
st_unaryunion(geometry: geometry) → geometry

Returns a union of the components for any geometry or geometry collection provided. Dissolves boundaries of a multipolygon.

+		Immutable
st_voronoilines(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoipolygons(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_wkbtosql(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_wkttosql(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_x(geometry: geometry) → float

Returns the X coordinate of a geometry if it is a Point.

+		Immutable
st_xmax(box2d: box2d) → float

Returns the maximum X ordinate of a box2d.

+		Immutable
st_xmax(geometry: geometry) → float

Returns the maximum X ordinate of a geometry.

+		Immutable
st_xmin(box2d: box2d) → float

Returns the minimum X ordinate of a box2d.

+		Immutable
st_xmin(geometry: geometry) → float

Returns the minimum X ordinate of a geometry.

+		Immutable
st_y(geometry: geometry) → float

Returns the Y coordinate of a geometry if it is a Point.

+		Immutable
st_ymax(box2d: box2d) → float

Returns the maximum Y ordinate of a box2d.

+		Immutable
st_ymax(geometry: geometry) → float

Returns the maximum Y ordinate of a geometry.

+		Immutable
st_ymin(box2d: box2d) → float

Returns the minimum Y ordinate of a box2d.

+		Immutable
st_ymin(geometry: geometry) → float

Returns the minimum Y ordinate of a geometry.

+		Immutable
st_z(geometry: geometry) → float

Returns the Z coordinate of a geometry if it is a Point.

+		Immutable
st_zmflag(geometry: geometry) → int2

Returns a code based on the ZM coordinate dimension of a geometry (XY = 0, XYM = 1, XYZ = 2, XYZM = 3).

+		Immutable
+ +### String and byte functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ascii(val: string) → int

Returns the character code of the first character in val. Despite the name, the function supports Unicode too.

+		Immutable
bit_length(val: bytes) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: string) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
btrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning or end of input (applies recursively).

+

For example, btrim('doggie', 'eod') returns ggi.

+		Immutable
btrim(val: string) → string

Removes all spaces from the beginning and end of val.

+		Immutable
char_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
char_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
character_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
character_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
chr(val: int) → string

Returns the character with the code given in val. Inverse function of ascii().

+		Immutable
compress(data: bytes, codec: string) → bytes

Compress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
concat(string...) → string

Concatenates a comma-separated list of strings.

+		Immutable
concat_ws(string...) → string

Uses the first argument as a separator between the concatenation of the subsequent arguments.

+

For example concat_ws('!','wow','great') returns wow!great.

+		Immutable
convert_from(str: bytes, enc: string) → string

Decode the bytes in str into a string using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
convert_to(str: string, enc: string) → bytes

Encode the string str as a byte array using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
crdb_internal.decode_external_plan_gist(gist: string) → string

Returns rows of output similar to EXPLAIN from a gist such as those found in planGists element of the statistics column of the statement_statistics table without attempting to resolve tables or indexes.

+		Volatile
crdb_internal.decode_plan_gist(gist: string) → string

Returns rows of output similar to EXPLAIN from a gist such as those found in planGists element of the statistics column of the statement_statistics table.

+		Volatile
crdb_internal.gen_rand_ident(name_pattern: string, count: int) → string

Returns random SQL identifiers.

+

gen_rand_ident(pattern, count) is an alias for gen_rand_ident(pattern, count, ‘’). +See the documentation of the other gen_rand_ident overload for details.

+		Volatile
crdb_internal.gen_rand_ident(name_pattern: string, count: int, parameters: jsonb) → string

Returns count random SQL identifiers that resemble the name_pattern.

+

The last argument is a JSONB object containing the following optional fields:

+
    +
  • “seed”: the seed to use for the pseudo-random generator (default: random).
    • +
  • “number”: whether to add a number to the generated names (default true). +When enabled, occurrences of the character ‘#’ in the name pattern are +replaced by the number. If ‘#’ is not present, the number is added at the end.
    • +
  • “noise”: whether to add noise to the generated names (default true). +It adds a non-zero probability for each of the probability options below left to zero. +(To enable noise generally but disable one type of noise, set its probability to -1.)
    • +
  • “punctuate”: probability of adding punctuation.
    • +
  • “fmt”: probability of adding random Go/C formatting directives.
    • +
  • “escapes”: probability of adding random escape sequences.
    • +
  • “quote”: probabiltiy of adding single or double quotes.
    • +
  • “emote”: probability of adding emojis.
    • +
  • “space”: probability of adding simple spaces.
    • +
  • “whitespace”: probability of adding complex whitespace.
    • +
  • “capitals”: probability of using capital letters. +Note: the name pattern must contain ASCII letters already for capital letters to be used.
    • +
  • “diacritics”: probability of adding diacritics.
    • +
  • “diacritic_depth”: max number of diacritics to add at a time (default 1).
    • +
  • “zalgo”: special option that overrides diacritics and diacritic_depth (default false).
    • +
+		Volatile
crdb_internal.show_create_all_schemas(database_name: string) → string

Returns rows of CREATE schema statements. +The output can be used to recreate a database.’

+		Volatile
crdb_internal.show_create_all_tables(database_name: string) → string

Returns rows of CREATE table statements followed by +ALTER table statements that add table constraints. The rows are ordered +by dependencies. All foreign keys are added after the creation of the table +in the alter statements. +It is not recommended to perform this operation on a database with many +tables. +The output can be used to recreate a database.’

+		Volatile
crdb_internal.show_create_all_types(database_name: string) → string

Returns rows of CREATE type statements. +The output can be used to recreate a database.’

+		Volatile
decode(text: string, format: string) → bytes

Decodes data using format (hex / escape / base64).

+		Immutable
decompress(data: bytes, codec: string) → bytes

Decompress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
difference(source: string, target: string) → int

Convert two strings to their Soundex codes and then reports the number of matching code positions.

+		Immutable
encode(data: bytes, format: string) → string

Encodes data using format (hex / escape / base64).

+		Immutable
format(string, anyelement...) → string

Interprets the first argument as a format string similar to C sprintf and interpolates the remaining arguments.

+		Stable
from_ip(val: bytes) → string

Converts the byte string representation of an IP to its character string representation.

+		Immutable
from_uuid(val: bytes) → string

Converts the byte string representation of a UUID to its character string representation.

+		Immutable
get_bit(bit_string: varbit, index: int) → int

Extracts a bit at given index in the bit array.

+		Immutable
get_bit(byte_string: bytes, index: int) → int

Extracts a bit at the given index in the byte array.

+		Immutable
get_byte(byte_string: bytes, index: int) → int

Extracts a byte at the given index in the byte array.

+		Immutable
initcap(val: string) → string

Capitalizes the first letter of val.

+		Immutable
left(input: bytes, return_set: int) → bytes

Returns the first return_set bytes from input.

+		Immutable
left(input: string, return_set: int) → string

Returns the first return_set characters from input.

+		Immutable
length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
length(val: string) → int

Calculates the number of characters in val.

+		Immutable
length(val: varbit) → int

Calculates the number of bits in val.

+		Immutable
lower(val: string) → string

Converts all characters in val to their lower-case equivalents.

+		Immutable
lpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the left of string.If string is longer than length it is truncated.

+		Immutable
lpad(string: string, length: int, fill: string) → string

Pads string by adding fill to the left of string to make it length. If string is longer than length it is truncated.

+		Immutable
ltrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning (left-hand side) of input (applies recursively).

+

For example, ltrim('doggie', 'od') returns ggie.

+		Immutable
ltrim(val: string) → string

Removes all spaces from the beginning (left-hand side) of val.

+		Immutable
md5(bytes...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
md5(string...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
octet_length(val: bytes) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: string) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int) → string

Replaces characters in input with overlay_val starting at start_pos (begins at 1).

+

For example, overlay('doggie', 'CAT', 2) returns dCATie.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int, end_pos: int) → string

Deletes the characters in input between start_pos and end_pos (count starts at 1), and then insert overlay_val at start_pos.

+		Immutable
parse_date(string: string, datestyle: string) → date

Parses a date assuming it is in format specified by DateStyle.

+		Immutable
parse_date(val: string) → date

Parses a date assuming it is in MDY format.

+		Immutable
parse_ident(qualified_identifier: string) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. Extra characters after the last identifier are considered an error

+		Immutable
parse_ident(qualified_identifier: string, strict: bool) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. If strict is false, then extra characters after the last identifier are ignored.

+		Immutable
parse_interval(string: string, style: string) → interval

Convert a string to an interval using the given IntervalStyle.

+		Immutable
parse_interval(val: string) → interval

Convert a string to an interval assuming the Postgres IntervalStyle.

+		Immutable
parse_time(string: string, timestyle: string) → time

Parses a time assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_time(val: string) → time

Parses a time assuming the date (if any) is in MDY format.

+		Immutable
parse_timestamp(string: string, datestyle: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates formatted using the given DateStyle.

+		Immutable
parse_timestamp(val: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates are in MDY format.

+		Immutable
parse_timetz(string: string, timestyle: string) → timetz

Parses a timetz assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_timetz(val: string) → timetz

Parses a timetz assuming the date (if any) is in MDY format.

+		Immutable
prettify_statement(statement: string, line_width: int, align_mode: int, case_mode: int) → string

Prettifies a statement using a user-configured pretty-printing config. +Align mode values range from 0 - 3, representing no, partial, full, and extra alignment respectively. +Case mode values range between 0 - 1, representing lower casing and upper casing respectively.

+		Immutable
prettify_statement(val: string) → string

Prettifies a statement using a the default pretty-printing config.

+		Immutable
quote_ident(val: string) → string

Return val suitably quoted to serve as identifier in a SQL statement.

+		Immutable
quote_literal(val: string) → string

Return val suitably quoted to serve as string literal in a SQL statement.

+		Immutable
quote_literal(val: anyelement) → string

Coerce val to a string and then quote it as a literal.

+		Stable
quote_nullable(val: string) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Immutable
quote_nullable(val: anyelement) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Stable
regexp_extract(input: string, regex: string) → string

Returns the first match for the Regular Expression regex in input.

+		Immutable
regexp_replace(input: string, regex: string, replace: string) → string

Replaces matches for the Regular Expression regex in input with the Regular Expression replace.

+		Immutable
regexp_replace(input: string, regex: string, replace: string, flags: string) → string

Replaces matches for the regular expression regex in input with the regular expression replace using flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
repeat(input: string, repeat_counter: int) → string

Concatenates input repeat_counter number of times.

+

For example, repeat('dog', 2) returns dogdog.

+		Immutable
replace(input: string, find: string, replace: string) → string

Replaces all occurrences of find with replace in input

+		Immutable
reverse(val: string) → string

Reverses the order of the string’s characters.

+		Immutable
right(input: bytes, return_set: int) → bytes

Returns the last return_set bytes from input.

+		Immutable
right(input: string, return_set: int) → string

Returns the last return_set characters from input.

+		Immutable
rpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the right of string. If string is longer than length it is truncated.

+		Immutable
rpad(string: string, length: int, fill: string) → string

Pads string to length by adding fill to the right of string. If string is longer than length it is truncated.

+		Immutable
rtrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the end (right-hand side) of input (applies recursively).

+

For example, rtrim('doggie', 'ei') returns dogg.

+		Immutable
rtrim(val: string) → string

Removes all spaces from the end (right-hand side) of val.

+		Immutable
set_bit(bit_string: varbit, index: int, to_set: int) → varbit

Updates a bit at given index in the bit array.

+		Immutable
set_bit(byte_string: bytes, index: int, to_set: int) → bytes

Updates a bit at the given index in the byte array.

+		Immutable
set_byte(byte_string: bytes, index: int, to_set: int) → bytes

Updates a byte at the given index in the byte array.

+		Immutable
sha1(bytes...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha1(string...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha224(bytes...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha224(string...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha256(bytes...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha256(string...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha384(bytes...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha384(string...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha512(bytes...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
sha512(string...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
similar_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_to_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
split_part(input: string, delimiter: string, return_index_pos: int) → string

Splits input on delimiter and return the value in the return_index_pos position (starting at 1).

+

For example, split_part('123.456.789.0','.',3)returns 789.

+		Immutable
strpos(input: bytes, find: bytes) → int

Calculates the position where the byte subarray find begins in input.

+		Immutable
strpos(input: string, find: string) → int

Calculates the position where the string find begins in input.

+

For example, strpos('doggie', 'gie') returns 4.

+		Immutable
strpos(input: varbit, find: varbit) → int

Calculates the position where the bit subarray find begins in input.

+		Immutable
substr(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substr(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substr(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substring(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substring(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
to_char_with_style(date: date, datestyle: string) → string

Convert an date to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_char_with_style(interval: interval, style: string) → string

Convert an interval to a string using the given IntervalStyle.

+		Immutable
to_char_with_style(timestamp: timestamp, datestyle: string) → string

Convert an timestamp to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_english(val: int) → string

This function enunciates the value of its argument using English cardinals.

+		Immutable
to_hex(val: bytes) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: int) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: string) → string

Converts val to its hexadecimal representation.

+		Immutable
to_ip(val: string) → bytes

Converts the character string representation of an IP to its byte string representation.

+		Immutable
to_uuid(val: string) → bytes

Converts the character string representation of a UUID to its byte string representation.

+		Immutable
translate(input: string, find: string, replace: string) → string

In input, replaces the first character from find with the first character in replace; repeat for each character in find.

+

For example, translate('doggie', 'dog', '123'); returns 1233ie.

+		Immutable
ulid_to_uuid(val: string) → uuid

Converts a ULID string to its UUID-encoded representation.

+		Immutable
unaccent(val: string) → string

Removes accents (diacritic signs) from the text provided in val.

+		Immutable
upper(val: string) → string

Converts all characters in val to their to their upper-case equivalents.

+		Immutable
+ +### System info functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cluster_logical_timestamp() → decimal

Returns the logical time of the current transaction as +a CockroachDB HLC in decimal form.

+

Note that uses of this function disable server-side optimizations and +may increase either contention or retry errors, or both.

+		Volatile
crdb_internal.active_version() → jsonb

Returns the current active cluster version.

+		Volatile
crdb_internal.approximate_timestamp(timestamp: decimal) → timestamp

Converts the crdb_internal_mvcc_timestamp column into an approximate timestamp.

+		Immutable
crdb_internal.assignment_cast(val: anyelement, type: anyelement) → anyelement

This function is used internally to perform assignment casts during mutations.

+		Stable
crdb_internal.check_consistency(stats_only: bool, start_key: bytes, end_key: bytes) → tuple{int AS range_id, bytes AS start_key, string AS start_key_pretty, string AS status, string AS detail, interval AS duration}

Runs a consistency check on ranges touching the specified key range. an empty start or end key is treated as the minimum and maximum possible, respectively. stats_only should only be set to false when targeting a small number of ranges to avoid overloading the cluster. Each returned row contains the range ID, the status (a roachpb.CheckConsistencyResponse_Status), and verbose detail.

+

Example usage:

+

SELECT * FROM crdb_internal.check_consistency(true, b'\x02', b'\x04')

+		Volatile
crdb_internal.check_password_hash_format(password: bytes) → string

This function checks whether a string is a precomputed password hash. Returns the hash algorithm.

+		Immutable
crdb_internal.cluster_id() → uuid

Returns the logical cluster ID for this tenant.

+		Stable
crdb_internal.cluster_name() → string

Returns the cluster name.

+		Volatile
crdb_internal.cluster_setting_encoded_default(setting: string) → string

Returns the encoded default value of the given cluster setting.

+		Immutable
crdb_internal.create_join_token() → string

Creates a join token for use when adding a new node to a secure cluster.

+		Volatile
crdb_internal.create_session_revival_token() → bytes

Generate a token that can be used to create a new session for the current user.

+		Volatile
crdb_internal.create_sql_schema_telemetry_job() → int

This function is used to create a schema telemetry job instance.

+		Volatile
crdb_internal.decode_cluster_setting(setting: string, value: string) → string

Decodes the given encoded value for a cluster setting.

+		Immutable
crdb_internal.deserialize_session(session: bytes) → bool

This function deserializes the serialized variables into the current session.

+		Volatile
crdb_internal.encode_key(table_id: int, index_id: int, row_tuple: anyelement) → bytes

Generate the key for a row on a particular table and index.

+		Stable
crdb_internal.fingerprint(span: bytes[], start_time: decimal, all_revisions: bool) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Stable
crdb_internal.fingerprint(span: bytes[], start_time: timestamptz, all_revisions: bool) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Stable
crdb_internal.fingerprint(span: bytes[], stripped: bool) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Stable
crdb_internal.force_assertion_error(msg: string) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Volatile
crdb_internal.force_error(errorCode: string, msg: string) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Volatile
crdb_internal.force_log_fatal(msg: string) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Volatile
crdb_internal.force_panic(msg: string) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Volatile
crdb_internal.force_panic(msg: string, mode: string) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Volatile
crdb_internal.force_retry(val: interval) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Volatile
crdb_internal.generate_test_objects(names: string, counts: int[]) → jsonb

Generates a number of objects whose name follow the provided pattern.

+

generate_test_objects(pat, counts) is an alias for +generate_test_objects(’{“names”:pat, “counts”:counts}’::jsonb)

+		Volatile
crdb_internal.generate_test_objects(names: string, number: int) → jsonb

Generates a number of objects whose name follow the provided pattern.

+

generate_test_objects(pat, num) is an alias for +generate_test_objects(’{“names”:pat, “counts”:[num]}’::jsonb)

+		Volatile
crdb_internal.generate_test_objects(parameters: jsonb) → jsonb

Generates a number of objects whose name follow the provided pattern.

+

Parameters:

+
    +
  • “names”: pattern to use to name the generated objects (default: +“test”).
    • +
  • “counts”: counts of generated objects (default: [10]).
    • +
  • “dry_run”: prepare the schema but do not actually write it +(default: false).
    • +
  • “seed”: random seed to use (default: auto).
    • +
  • “randomize_columns”: whether to randomize the column names on tables +(default: true).
    • +
  • “table_templates”: table templates to use. +If the last part of “names” is “_”, the name of the template +will be used as base pattern during name generation for tables. +Otherwise, the last part of “names” will be used as pattern. +If no table templates are specified, a simple template is used.
    • +
  • “name_gen”: configuration for the name generation, see below.
    • +
+

Name generation options:

+
    +
  • “number”: whether to add a number to the generated names (default true). +When enabled, occurrences of the character ‘#’ in the name pattern are +replaced by the number. If ‘#’ is not present, the number is added at the end.
    • +
  • “noise”: whether to add noise to the generated names (default true). +It adds a non-zero probability for each of the probability options below left to zero. +(To enable noise generally but disable one type of noise, set its probability to -1.)
    • +
  • “punctuate”: probability of adding punctuation.
    • +
  • “fmt”: probability of adding random Go/C formatting directives.
    • +
  • “escapes”: probability of adding random escape sequences.
    • +
  • “quote”: probabiltiy of adding single or double quotes.
    • +
  • “emote”: probability of adding emojis.
    • +
  • “space”: probability of adding simple spaces.
    • +
  • “whitespace”: probability of adding complex whitespace.
    • +
  • “capitals”: probability of using capital letters. +Note: the name pattern must contain ASCII letters already for capital letters to be used.
    • +
  • “diacritics”: probability of adding diacritics.
    • +
  • “diacritic_depth”: max number of diacritics to add at a time (default 1).
    • +
  • “zalgo”: special option that overrides diacritics and diacritic_depth (default false).
    • +
+		Volatile
crdb_internal.get_database_id(name: string) → intStable
crdb_internal.get_namespace_id(parent_id: int, name: string) → intStable
crdb_internal.get_namespace_id(parent_id: int, parent_schema_id: int, name: string) → intStable
crdb_internal.get_vmodule() → string

Returns the vmodule configuration on the gateway node processing this request.

+		Volatile
crdb_internal.get_zone_config(namespace_id: int) → bytesStable
crdb_internal.has_role_option(option: string) → bool

Returns whether the current user has the specified role option

+		Stable
crdb_internal.index_span(table_id: int, index_id: int) → bytes[]

This function returns the span that contains the keys for the given index.

+		Leakproof
crdb_internal.is_admin() → bool

Retrieves the current user’s admin status.

+		Stable
crdb_internal.is_at_least_version(version: string) → bool

Returns true if the cluster version is not older than the argument.

+		Volatile
crdb_internal.is_constraint_active(table_name: string, constraint_name: string) → bool

This function is used to determine if a given constraint is currently. +active for the current transaction.

+		Volatile
crdb_internal.lease_holder(key: bytes) → int

This function is used to fetch the leaseholder corresponding to a request key

+		Volatile
crdb_internal.list_sql_keys_in_range(range_id: int) → tuple{string AS key, string AS value, string AS ts}

Returns all SQL K/V pairs within the requested range.

+		Volatile
crdb_internal.locality_value(key: string) → string

Returns the value of the specified locality key.

+		Stable
crdb_internal.no_constant_folding(input: anyelement) → anyelement

This function is used only by CockroachDB’s developers for testing purposes.

+		Volatile
crdb_internal.node_executable_version() → string

Returns the version of CockroachDB this node is running.

+		Volatile
crdb_internal.node_id() → int

Returns the node ID.

+		Stable
crdb_internal.notice(msg: string) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Volatile
crdb_internal.notice(severity: string, msg: string) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Volatile
crdb_internal.num_geo_inverted_index_entries(table_id: int, index_id: int, val: geography) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Stable
crdb_internal.num_geo_inverted_index_entries(table_id: int, index_id: int, val: geometry) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Stable
crdb_internal.num_inverted_index_entries(val: string, version: int) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Stable
crdb_internal.num_inverted_index_entries(val: anyelement[]) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Stable
crdb_internal.num_inverted_index_entries(val: anyelement[], version: int) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Stable
crdb_internal.num_inverted_index_entries(val: jsonb) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Stable
crdb_internal.num_inverted_index_entries(val: jsonb, version: int) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Stable
crdb_internal.num_inverted_index_entries(val: tsvector, version: int) → int

This function is used only by CockroachDB’s developers for testing purposes.

+		Stable
crdb_internal.payloads_for_span(span_id: int) → tuple{string AS payload_type, jsonb AS payload_jsonb}

Returns the payload(s) of the requested span and all its children.

+		Volatile
crdb_internal.payloads_for_trace(trace_id: int) → tuple{int AS span_id, string AS payload_type, jsonb AS payload_jsonb}

Returns the payload(s) of the requested trace.

+		Volatile
crdb_internal.pretty_key(raw_key: bytes, skip_fields: int) → string

This function is used only by CockroachDB’s developers for testing purposes.

+		Immutable
crdb_internal.pretty_span(raw_key_start: bytes, raw_key_end: bytes, skip_fields: int) → string

This function is used only by CockroachDB’s developers for testing purposes.

+		Immutable
crdb_internal.range_stats(key: bytes) → jsonb

This function is used to retrieve range statistics information as a JSON object.

+		Volatile
crdb_internal.read_file(uri: string) → bytes

Read the content of the file at the supplied external storage URI

+		Volatile
crdb_internal.repair_ttl_table_scheduled_job(oid: oid) → void

Repairs the scheduled job for a TTL table if it is missing.

+		Volatile
crdb_internal.request_statement_bundle(stmtFingerprint: string, samplingProbability: float, minExecutionLatency: interval, expiresAfter: interval) → bool

Used to request statement bundle for a given statement fingerprint +that has execution latency greater than the ‘minExecutionLatency’. If the +‘expiresAfter’ argument is empty, then the statement bundle request never +expires until the statement bundle is collected

+		Volatile
crdb_internal.reset_activity_tables() → bool

This function is used to clear the {statement|transaction} activity system tables.

+		Volatile
crdb_internal.reset_index_usage_stats() → bool

This function is used to clear the collected index usage statistics.

+		Volatile
crdb_internal.reset_sql_stats() → bool

This function is used to clear the collected SQL statistics.

+		Volatile
crdb_internal.revalidate_unique_constraint(table_name: string, constraint_name: string) → void

This function is used to revalidate the given unique constraint in the given +table. Returns an error if validation fails.

+		Volatile
crdb_internal.revalidate_unique_constraints_in_all_tables() → void

This function is used to revalidate all unique constraints in tables +in the current database. Returns an error if validation fails.

+		Volatile
crdb_internal.revalidate_unique_constraints_in_table(table_name: string) → void

This function is used to revalidate all unique constraints in the given +table. Returns an error if validation fails.

+		Volatile
crdb_internal.round_decimal_values(val: decimal, scale: int) → decimal

This function is used internally to round decimal values during mutations.

+		Immutable
crdb_internal.round_decimal_values(val: decimal[], scale: int) → decimal[]

This function is used internally to round decimal array values during mutations.

+		Stable
crdb_internal.schedule_sql_stats_compaction() → bool

This function is used to start a SQL stats compaction job.

+		Volatile
crdb_internal.serialize_session() → bytes

This function serializes the variables in the current session.

+		Volatile
crdb_internal.set_trace_verbose(trace_id: int, verbosity: bool) → bool

Returns true if root span was found and verbosity was set, false otherwise.

+		Volatile
crdb_internal.set_vmodule(vmodule_string: string) → int

Set the equivalent of the --vmodule flag on the gateway node processing this request; it affords control over the logging verbosity of different files. Example syntax: crdb_internal.set_vmodule('recordio=2,file=1,gfs*=3'). Reset with: crdb_internal.set_vmodule(''). Raising the verbosity can severely affect performance.

+		Volatile
crdb_internal.table_span(table_id: int) → bytes[]

This function returns the span that contains the keys for the given table.

+		Leakproof
crdb_internal.trace_id() → int

Returns the current trace ID or an error if no trace is open.

+		Volatile
crdb_internal.unsafe_clear_gossip_info(key: string) → bool

This function is used only by CockroachDB’s developers for testing purposes.

+		Volatile
crdb_internal.validate_session_revival_token(token: bytes) → bool

Validate a token that was created by create_session_revival_token. Intended for testing.

+		Volatile
crdb_internal.validate_ttl_scheduled_jobs() → void

Validate all TTL tables have a valid scheduled job attached.

+		Volatile
crdb_internal.void_func() → void

This function is used only by CockroachDB’s developers for testing purposes.

+		Volatile
crdb_internal.write_file(data: bytes, uri: string) → int

Write the content passed to a file at the supplied external storage URI

+		Volatile
current_database() → string

Returns the current database.

+		Stable
current_schema() → string

Returns the current schema.

+		Stable
current_schemas(include_pg_catalog: bool) → string[]

Returns the valid schemas in the search path.

+		Stable
current_user() → string

Returns the current user. This function is provided for compatibility with PostgreSQL.

+		Stable
session_user() → string

Returns the session user. This function is provided for compatibility with PostgreSQL.

+		Stable
to_regclass(text: string) → regtype

Translates a textual relation name to its OID

+		Stable
to_regnamespace(text: string) → regtype

Translates a textual schema name to its OID

+		Stable
to_regproc(text: string) → regtype

Translates a textual function or procedure name to its OID

+		Stable
to_regprocedure(text: string) → regtype

Translates a textual function or procedure name(with argument types) to its OID

+		Stable
to_regrole(text: string) → regtype

Translates a textual role name to its OID

+		Stable
to_regtype(text: string) → regtype

Translates a textual type name to its OID

+		Stable
version() → string

Returns the node’s version of CockroachDB.

+		Volatile
+ +### System repair functions + + + + + + +
Function → ReturnsDescriptionVolatility
crdb_internal.force_delete_table_data(id: int) → bool

This function can be used to clear the data belonging to a table, when the table cannot be dropped.

+		Volatile
crdb_internal.repair_catalog_corruption(descriptor_id: int, corruption: string) → bool

repair_catalog_corruption(descriptor_id,corruption) attempts to repair corrupt records in system tables associated with that descriptor id

+		Volatile
+ +### TIMETZ functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
current_time() → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time() → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_time(precision: int) → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time(precision: int) → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → timetz

Returns the current transaction’s time with time zone.

+		Stable
localtime(precision: int) → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime(precision: int) → timetz

Returns the current transaction’s time with time zone.

+		Stable
+ +### Trigrams functions + + + + + + +
Function → ReturnsDescriptionVolatility
show_trgm(input: string) → string[]

Returns an array of all the trigrams in the given string.

+		Immutable
similarity(left: string, right: string) → float

Returns a number that indicates how similar the two arguments are. The range of the result is zero (indicating that the two strings are completely dissimilar) to one (indicating that the two strings are identical).

+		Immutable
+ +### UUID functions + + + + + +
Function → ReturnsDescriptionVolatility
uuid_to_ulid(val: uuid) → string

Converts a UUID-encoded ULID to its string representation.

+		Immutable
+ +### Compatibility functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
col_description(table_oid: oid, column_number: int) → string

Returns the comment for a table column, which is specified by the OID of its table and its column number. (obj_description cannot be used for table columns, since columns do not have OIDs of their own.)

+		Stable
current_setting(setting_name: string) → string

System info

+		Stable
current_setting(setting_name: string, missing_ok: bool) → string

System info

+		Stable
format_type(type_oid: oid, typemod: int) → string

Returns the SQL name of a data type that is identified by its type OID and possibly a type modifier. Currently, the type modifier is ignored.

+		Stable
getdatabaseencoding() → string

Returns the current encoding name used by the database.

+		Stable
has_any_column_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_column_privilege(table: string, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: string, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_database_privilege(database: string, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(database: oid, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(user: string, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: string, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_foreign_data_wrapper_privilege(fdw: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(fdw: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_function_privilege(function: string, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(function: oid, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(user: string, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: string, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_language_privilege(language: string, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(language: oid, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(user: string, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: string, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_schema_privilege(schema: string, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(schema: oid, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_sequence_privilege(sequence: string, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(sequence: oid, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_server_privilege(server: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(server: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_table_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_tablespace_privilege(tablespace: string, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(tablespace: oid, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_type_privilege(type: string, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(type: oid, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(user: string, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: string, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
information_schema._pg_numeric_precision(typid: oid, typmod: int4) → int

Returns the precision of the given type with type modifier

+		Immutable
information_schema._pg_numeric_precision_radix(typid: oid, typmod: int4) → int

Returns the radix of the given type with type modifier

+		Immutable
information_schema._pg_numeric_scale(typid: oid, typmod: int4) → int

Returns the scale of the given type with type modifier

+		Immutable
obj_description(object_oid: oid) → string

Returns the comment for a database object specified by its OID alone. This is deprecated since there is no guarantee that OIDs are unique across different system catalogs; therefore, the wrong comment might be returned.

+		Stable
obj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a database object specified by its OID and the name of the containing system catalog. For example, obj_description(123456, ‘pg_class’) would retrieve the comment for the table with OID 123456.

+		Stable
oidvectortypes(vector: oidvector) → string

Generates a comma seperated string of type names from an oidvector.

+		Stable
pg_backend_pid() → int

Returns a numerical ID attached to this session. This ID is part of the query cancellation key used by the wire protocol. This function was only added for compatibility, and unlike in Postgres, the returned value does not correspond to a real process ID.

+		Stable
pg_collation_for(str: anyelement) → string

Returns the collation of the argument

+		Stable
pg_column_is_updatable(reloid: oid, attnum: int2, include_triggers: bool) → bool

Returns whether the given column can be updated.

+		Stable
pg_column_size(anyelement...) → int

Return size in bytes of the column provided as an argument

+		Immutable
pg_function_is_visible(oid: oid) → bool

Returns whether the function with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_get_function_arguments(func_oid: oid) → string

Returns the argument list (with defaults) necessary to identify a function, in the form it would need to appear in within CREATE FUNCTION.

+		Stable
pg_get_function_identity_arguments(func_oid: oid) → string

Returns the argument list (without defaults) necessary to identify a function, in the form it would need to appear in within ALTER FUNCTION, for instance.

+		Stable
pg_get_function_result(func_oid: oid) → string

Returns the types of the result of the specified function.

+		Stable
pg_get_functiondef(func_oid: oid) → string

For user-defined functions, returns the definition of the specified function. For builtin functions, returns the name of the function.

+		Stable
pg_get_indexdef(index_oid: oid) → string

Gets the CREATE INDEX command for index

+		Stable
pg_get_indexdef(index_oid: oid, column_no: int, pretty_bool: bool) → string

Gets the CREATE INDEX command for index, or definition of just one index column when given a non-zero column number

+		Stable
pg_get_serial_sequence(table_name: string, column_name: string) → string

Returns the name of the sequence used by the given column_name in the table table_name.

+		Stable
pg_get_viewdef(view_oid: oid) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_get_viewdef(view_oid: oid, pretty_bool: bool) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_has_role(role: string, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(role: oid, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(user: string, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: string, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_is_other_temp_schema(oid: oid) → bool

Returns true if the given OID is the OID of another session’s temporary schema. (This can be useful, for example, to exclude other sessions’ temporary tables from a catalog display.)

+		Stable
pg_my_temp_schema() → oid

Returns the OID of the current session’s temporary schema, or zero if it has none (because it has not created any temporary tables).

+		Stable
pg_relation_is_updatable(reloid: oid, include_triggers: bool) → int4

Returns the update events the relation supports.

+		Stable
pg_sleep(seconds: float) → bool

pg_sleep makes the current session’s process sleep until seconds seconds have elapsed. seconds is a value of type double precision, so fractional-second delays can be specified.

+		Volatile
pg_table_is_visible(oid: oid) → bool

Returns whether the table with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_type_is_visible(oid: oid) → bool

Returns whether the type with the given OID belongs to one of the schemas on the search path.

+		Stable
set_config(setting_name: string, new_value: string, is_local: bool) → string

System info

+		Volatile
shobj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a shared database object specified by its OID and the name of the containing system catalog. This is just like obj_description except that it is used for retrieving comments on shared objects (e.g. databases).

+		Stable
+ diff --git a/src/current/_includes/cockroach-generated/release-23.1/sql/operators.md b/src/current/_includes/cockroach-generated/release-23.1/sql/operators.md new file mode 100644 index 00000000000..e7c7f1e20f3 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-23.1/sql/operators.md @@ -0,0 +1,610 @@ + + + + + +
#Return
int # intint
varbit # varbitvarbit
+ + + + +
#>Return
jsonb #> string[]jsonb
+ + + + +
#>>Return
jsonb #>> string[]string
+ + + + + + + + + +
%Return
decimal % decimaldecimal
decimal % intdecimal
float % floatfloat
int % decimaldecimal
int % intint
string % stringbool
+ + + + + + +
&Return
inet & inetinet
int & intint
varbit & varbitvarbit
+ + + + + + + + + +
&&Return
anyelement && anyelementbool
box2d && box2dbool
box2d && geometrybool
geometry && box2dbool
geometry && geometrybool
inet && inetbool
+ + + + + + + + + + + + + + +
*Return
decimal * decimaldecimal
decimal * intdecimal
decimal * intervalinterval
float * floatfloat
float * intervalinterval
int * decimaldecimal
int * intint
int * intervalinterval
interval * decimalinterval
interval * floatinterval
interval * intinterval
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Return
+decimaldecimal
+floatfloat
+intint
+intervalinterval
date + intdate
date + intervaltimestamp
date + timetimestamp
date + timetztimestamptz
decimal + decimaldecimal
decimal + intdecimal
float + floatfloat
inet + intinet
int + datedate
int + decimaldecimal
int + inetinet
int + intint
interval + datetimestamp
interval + intervalinterval
interval + timetime
interval + timestamptimestamp
interval + timestamptztimestamptz
interval + timetztimetz
time + datetimestamp
time + intervaltime
timestamp + intervaltimestamp
timestamptz + intervaltimestamptz
timetz + datetimestamptz
timetz + intervaltimetz
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
-Return
-decimaldecimal
-floatfloat
-intint
-intervalinterval
date - dateint
date - intdate
date - intervaltimestamp
date - timetimestamp
decimal - decimaldecimal
decimal - intdecimal
float - floatfloat
inet - inetint
inet - intinet
int - decimaldecimal
int - intint
interval - intervalinterval
jsonb - intjsonb
jsonb - stringjsonb
jsonb - string[]jsonb
time - intervaltime
time - timeinterval
timestamp - intervaltimestamp
timestamp - timestampinterval
timestamp - timestamptzinterval
timestamptz - intervaltimestamptz
timestamptz - timestampinterval
timestamptz - timestamptzinterval
timetz - intervaltimetz
+ + + + + +
->Return
jsonb -> intjsonb
jsonb -> stringjsonb
+ + + + + +
->>Return
jsonb ->> intstring
jsonb ->> stringstring
+ + + + + + + + + + +
/Return
decimal / decimaldecimal
decimal / intdecimal
float / floatfloat
int / decimaldecimal
int / intdecimal
interval / floatinterval
interval / intinterval
+ + + + + + + + +
//Return
decimal // decimaldecimal
decimal // intdecimal
float // floatfloat
int // decimaldecimal
int // intint
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<Return
anyenum < anyenumbool
bool < boolbool
bool[] < bool[]bool
box2d < box2dbool
bytes < bytesbool
bytes[] < bytes[]bool
collatedstring < collatedstringbool
date < datebool
date < timestampbool
date < timestamptzbool
date[] < date[]bool
decimal < decimalbool
decimal < floatbool
decimal < intbool
decimal[] < decimal[]bool
float < decimalbool
float < floatbool
float < intbool
float[] < float[]bool
geography < geographybool
geometry < geometrybool
inet < inetbool
inet[] < inet[]bool
int < decimalbool
int < floatbool
int < intbool
int < oidbool
int[] < int[]bool
interval < intervalbool
interval[] < interval[]bool
jsonb < jsonbbool
oid < intbool
oid < oidbool
string < stringbool
string[] < string[]bool
time < timebool
time < timetzbool
time[] < time[]bool
timestamp < datebool
timestamp < timestampbool
timestamp < timestamptzbool
timestamp[] < timestamp[]bool
timestamptz < datebool
timestamptz < timestampbool
timestamptz < timestamptzbool
timestamptz < timestamptzbool
timetz < timebool
timetz < timetzbool
tuple < tuplebool
uuid < uuidbool
uuid[] < uuid[]bool
varbit < varbitbool
+ + + + + + +
<<Return
inet << inetbool
int << intint
varbit << intvarbit
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<=Return
anyenum <= anyenumbool
bool <= boolbool
bool[] <= bool[]bool
box2d <= box2dbool
bytes <= bytesbool
bytes[] <= bytes[]bool
collatedstring <= collatedstringbool
date <= datebool
date <= timestampbool
date <= timestamptzbool
date[] <= date[]bool
decimal <= decimalbool
decimal <= floatbool
decimal <= intbool
decimal[] <= decimal[]bool
float <= decimalbool
float <= floatbool
float <= intbool
float[] <= float[]bool
geography <= geographybool
geometry <= geometrybool
inet <= inetbool
inet[] <= inet[]bool
int <= decimalbool
int <= floatbool
int <= intbool
int <= oidbool
int[] <= int[]bool
interval <= intervalbool
interval[] <= interval[]bool
jsonb <= jsonbbool
oid <= intbool
oid <= oidbool
string <= stringbool
string[] <= string[]bool
time <= timebool
time <= timetzbool
time[] <= time[]bool
timestamp <= datebool
timestamp <= timestampbool
timestamp <= timestamptzbool
timestamp[] <= timestamp[]bool
timestamptz <= datebool
timestamptz <= timestampbool
timestamptz <= timestamptzbool
timestamptz <= timestamptzbool
timetz <= timebool
timetz <= timetzbool
tuple <= tuplebool
uuid <= uuidbool
uuid[] <= uuid[]bool
varbit <= varbitbool
+ + + + + +
<@Return
anyelement <@ anyelementbool
jsonb <@ jsonbbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
=Return
anyenum = anyenumbool
bool = boolbool
bool[] = bool[]bool
box2d = box2dbool
bytes = bytesbool
bytes[] = bytes[]bool
collatedstring = collatedstringbool
date = datebool
date = timestampbool
date = timestamptzbool
date[] = date[]bool
decimal = decimalbool
decimal = floatbool
decimal = intbool
decimal[] = decimal[]bool
float = decimalbool
float = floatbool
float = intbool
float[] = float[]bool
geography = geographybool
geometry = geometrybool
inet = inetbool
inet[] = inet[]bool
int = decimalbool
int = floatbool
int = intbool
int = oidbool
int[] = int[]bool
interval = intervalbool
interval[] = interval[]bool
jsonb = jsonbbool
oid = intbool
oid = oidbool
string = stringbool
string[] = string[]bool
time = timebool
time = timetzbool
time[] = time[]bool
timestamp = datebool
timestamp = timestampbool
timestamp = timestamptzbool
timestamp[] = timestamp[]bool
timestamptz = datebool
timestamptz = timestampbool
timestamptz = timestamptzbool
timestamptz = timestamptzbool
timetz = timebool
timetz = timetzbool
tsquery = tsquerybool
tsvector = tsvectorbool
tuple = tuplebool
uuid = uuidbool
uuid[] = uuid[]bool
varbit = varbitbool
+ + + + + + +
>>Return
inet >> inetbool
int >> intint
varbit >> intvarbit
+ + + + +
?Return
jsonb ? stringbool
+ + + + +
?&Return
jsonb ?& string[]bool
+ + + + +
?|Return
jsonb ?| string[]bool
+ + + + + +
@>Return
anyelement @> anyelementbool
jsonb @> jsonbbool
+ + + + + +
@@Return
tsquery @@ tsvectorbool
tsvector @@ tsquerybool
+ + + + +
ILIKEReturn
string ILIKE stringbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
INReturn
anyenum IN tuplebool
bool IN tuplebool
box2d IN tuplebool
bytes IN tuplebool
collatedstring IN tuplebool
date IN tuplebool
decimal IN tuplebool
float IN tuplebool
geography IN tuplebool
geometry IN tuplebool
inet IN tuplebool
int IN tuplebool
interval IN tuplebool
jsonb IN tuplebool
oid IN tuplebool
string IN tuplebool
time IN tuplebool
timestamp IN tuplebool
timestamptz IN tuplebool
timetz IN tuplebool
tuple IN tuplebool
uuid IN tuplebool
varbit IN tuplebool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IS NOT DISTINCT FROMReturn
anyelement IS NOT DISTINCT FROM unknownbool
anyenum IS NOT DISTINCT FROM anyenumbool
bool IS NOT DISTINCT FROM boolbool
bool[] IS NOT DISTINCT FROM bool[]bool
box2d IS NOT DISTINCT FROM box2dbool
bytes IS NOT DISTINCT FROM bytesbool
bytes[] IS NOT DISTINCT FROM bytes[]bool
collatedstring IS NOT DISTINCT FROM collatedstringbool
date IS NOT DISTINCT FROM datebool
date IS NOT DISTINCT FROM timestampbool
date IS NOT DISTINCT FROM timestamptzbool
date[] IS NOT DISTINCT FROM date[]bool
decimal IS NOT DISTINCT FROM decimalbool
decimal IS NOT DISTINCT FROM floatbool
decimal IS NOT DISTINCT FROM intbool
decimal[] IS NOT DISTINCT FROM decimal[]bool
float IS NOT DISTINCT FROM decimalbool
float IS NOT DISTINCT FROM floatbool
float IS NOT DISTINCT FROM intbool
float[] IS NOT DISTINCT FROM float[]bool
geography IS NOT DISTINCT FROM geographybool
geometry IS NOT DISTINCT FROM geometrybool
inet IS NOT DISTINCT FROM inetbool
inet[] IS NOT DISTINCT FROM inet[]bool
int IS NOT DISTINCT FROM decimalbool
int IS NOT DISTINCT FROM floatbool
int IS NOT DISTINCT FROM intbool
int IS NOT DISTINCT FROM oidbool
int[] IS NOT DISTINCT FROM int[]bool
interval IS NOT DISTINCT FROM intervalbool
interval[] IS NOT DISTINCT FROM interval[]bool
jsonb IS NOT DISTINCT FROM jsonbbool
oid IS NOT DISTINCT FROM intbool
oid IS NOT DISTINCT FROM oidbool
string IS NOT DISTINCT FROM stringbool
string[] IS NOT DISTINCT FROM string[]bool
time IS NOT DISTINCT FROM timebool
time IS NOT DISTINCT FROM timetzbool
time[] IS NOT DISTINCT FROM time[]bool
timestamp IS NOT DISTINCT FROM datebool
timestamp IS NOT DISTINCT FROM timestampbool
timestamp IS NOT DISTINCT FROM timestamptzbool
timestamp[] IS NOT DISTINCT FROM timestamp[]bool
timestamptz IS NOT DISTINCT FROM datebool
timestamptz IS NOT DISTINCT FROM timestampbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timetz IS NOT DISTINCT FROM timebool
timetz IS NOT DISTINCT FROM timetzbool
tsquery IS NOT DISTINCT FROM tsquerybool
tsvector IS NOT DISTINCT FROM tsvectorbool
tuple IS NOT DISTINCT FROM tuplebool
unknown IS NOT DISTINCT FROM unknownbool
unknown IS NOT DISTINCT FROM voidbool
uuid IS NOT DISTINCT FROM uuidbool
uuid[] IS NOT DISTINCT FROM uuid[]bool
varbit IS NOT DISTINCT FROM varbitbool
void IS NOT DISTINCT FROM unknownbool
+ + + + +
LIKEReturn
string LIKE stringbool
+ + + + +
SIMILAR TOReturn
string SIMILAR TO stringbool
+ + + + + + + + +
^Return
decimal ^ decimaldecimal
decimal ^ intdecimal
float ^ floatfloat
int ^ decimaldecimal
int ^ intint
+ + + + + + +
|Return
inet | inetinet
int | intint
varbit | varbitvarbit
+ + + + + +
|/Return
|/decimaldecimal
|/floatfloat
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
||Return
bool || bool[]bool[]
bool || stringstring
bool[] || boolbool[]
bool[] || bool[]bool[]
box2d || box2dbox2d
box2d || stringstring
bytes || bytesbytes
bytes || bytes[]bytes[]
bytes[] || bytesbytes[]
bytes[] || bytes[]bytes[]
date || date[]date[]
date || stringstring
date[] || datedate[]
date[] || date[]date[]
decimal || decimal[]decimal[]
decimal || stringstring
decimal[] || decimaldecimal[]
decimal[] || decimal[]decimal[]
float || float[]float[]
float || stringstring
float[] || floatfloat[]
float[] || float[]float[]
geography || geographygeography
geography || stringstring
geometry || geometrygeometry
geometry || stringstring
inet || inet[]inet[]
inet || stringstring
inet[] || inetinet[]
inet[] || inet[]inet[]
int || int[]int[]
int || stringstring
int[] || intint[]
int[] || int[]int[]
interval || interval[]interval[]
interval || stringstring
interval[] || intervalinterval[]
interval[] || interval[]interval[]
jsonb || jsonbjsonb
jsonb || stringstring
oid || oidoid
oid || stringstring
string || boolstring
string || box2dstring
string || datestring
string || decimalstring
string || floatstring
string || geographystring
string || geometrystring
string || inetstring
string || intstring
string || intervalstring
string || jsonbstring
string || oidstring
string || stringstring
string || string[]string[]
string || timestring
string || timestampstring
string || timestamptzstring
string || timetzstring
string || tuplestring
string || uuidstring
string || varbitstring
string[] || stringstring[]
string[] || string[]string[]
time || stringstring
time || time[]time[]
time[] || timetime[]
time[] || time[]time[]
timestamp || stringstring
timestamp || timestamp[]timestamp[]
timestamp[] || timestamptimestamp[]
timestamp[] || timestamp[]timestamp[]
timestamptz || stringstring
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timetz || stringstring
timetz || timetztimetz
tuple || stringstring
uuid || stringstring
uuid || uuid[]uuid[]
uuid[] || uuiduuid[]
uuid[] || uuid[]uuid[]
varbit || stringstring
varbit || varbitvarbit
+ + + + + +
||/Return
||/decimaldecimal
||/floatfloat
+ + + + + + + + + + + +
~Return
~inetinet
~intint
~varbitvarbit
box2d ~ box2dbool
box2d ~ geometrybool
geometry ~ box2dbool
geometry ~ geometrybool
string ~ stringbool
+ + + + +
~*Return
string ~* stringbool
diff --git a/src/current/_includes/cockroach-generated/release-23.1/sql/window_functions.md b/src/current/_includes/cockroach-generated/release-23.1/sql/window_functions.md new file mode 100644 index 00000000000..aee326add40 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-23.1/sql/window_functions.md @@ -0,0 +1,377 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cume_dist() → float

Calculates the relative rank of the current row: (number of rows preceding or peer with current row) / (total rows).

+		Immutable
dense_rank() → int

Calculates the rank of the current row without gaps; this function counts peer groups.

+		Immutable
first_value(val: bool) → bool

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: bytes) → bytes

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: date) → date

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: decimal) → decimal

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: float) → float

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: inet) → inet

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: int) → int

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: interval) → interval

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: string) → string

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: time) → time

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: uuid) → uuid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: box2d) → box2d

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geography) → geography

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geometry) → geometry

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: oid) → oid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timetz) → timetz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: varbit) → varbit

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
lag(val: bool) → bool

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: bytes) → bytes

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: date) → date

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: date, n: int) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: decimal) → decimal

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: float) → float

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: float, n: int) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: inet) → inet

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: int) → int

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: int, n: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: interval) → interval

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: string) → string

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: string, n: int) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: time) → time

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: time, n: int) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamp) → timestamp

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz) → timestamptz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: uuid) → uuid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: box2d) → box2d

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geography) → geography

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geometry) → geometry

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: jsonb) → jsonb

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: oid) → oid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timetz) → timetz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: varbit) → varbit

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
last_value(val: bool) → bool

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: bytes) → bytes

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: date) → date

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: decimal) → decimal

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: float) → float

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: inet) → inet

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: int) → int

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: interval) → interval

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: string) → string

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: time) → time

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: uuid) → uuid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: box2d) → box2d

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geography) → geography

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geometry) → geometry

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: oid) → oid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timetz) → timetz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: varbit) → varbit

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
lead(val: bool) → bool

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: bytes) → bytes

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: date) → date

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: date, n: int) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: decimal) → decimal

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: float) → float

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: float, n: int) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: inet) → inet

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: int) → int

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: int, n: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: interval) → interval

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: string) → string

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: string, n: int) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: time) → time

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: time, n: int) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamp) → timestamp

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz) → timestamptz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: uuid) → uuid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: box2d) → box2d

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geography) → geography

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geometry) → geometry

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: jsonb) → jsonb

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: oid) → oid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timetz) → timetz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: varbit) → varbit

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
nth_value(val: bool, n: int) → bool

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: bytes, n: int) → bytes

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: date, n: int) → date

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: decimal, n: int) → decimal

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: float, n: int) → float

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: inet, n: int) → inet

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: int, n: int) → int

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: interval, n: int) → interval

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: string, n: int) → string

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: time, n: int) → time

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: uuid, n: int) → uuid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: box2d, n: int) → box2d

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geography, n: int) → geography

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geometry, n: int) → geometry

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: oid, n: int) → oid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timetz, n: int) → timetz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: varbit, n: int) → varbit

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
ntile(n: int) → int

Calculates an integer ranging from 1 to n, dividing the partition as equally as possible.

+		Immutable
percent_rank() → float

Calculates the relative rank of the current row: (rank - 1) / (total rows - 1).

+		Immutable
rank() → int

Calculates the rank of the current row with gaps; same as row_number of its first peer.

+		Immutable
row_number() → int

Calculates the number of the current row within its partition, counting from 1.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-23.2/eventlog.md b/src/current/_includes/cockroach-generated/release-23.2/eventlog.md new file mode 100644 index 00000000000..d5a6d773c29 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-23.2/eventlog.md @@ -0,0 +1,3314 @@ +Certain notable events are reported using a structured format. +Commonly, these notable events are also copied to the table +`system.eventlog`, unless the cluster setting +`server.eventlog.enabled` is unset. + +Additionally, notable events are copied to specific external logging +channels in log messages, where they can be collected for further processing. + +The sections below document the possible notable event types +in this version of CockroachDB. For each event type, a table +documents the possible fields. A field may be omitted from +an event if its value is empty or zero. + +A field is also considered "Sensitive" if it may contain +application-specific information or personally identifiable information (PII). In that case, +the copy of the event sent to the external logging channel +will contain redaction markers in a format that is compatible +with the redaction facilities in [`cockroach debug zip`](cockroach-debug-zip.html) +and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html), +provided the `redactable` functionality is enabled on the logging sink. + +Events not documented on this page will have an unstructured format in log messages. + +## Cluster-level events + +Events in this category pertain to an entire cluster and are +not relative to any particular tenant. + +In a multi-tenant setup, the `system.eventlog` table for individual +tenants cannot contain a copy of cluster-level events; conversely, +the `system.eventlog` table in the system tenant cannot contain the +SQL-level events for individual tenants. + +Events in this category are logged to the `OPS` channel. + + +### `certs_reload` + +An event of type `certs_reload` is recorded when the TLS certificates are +reloaded/rotated from disk. + + +| Field | Description | Sensitive | +|--|--|--| +| `Success` | Whether the operation completed without errors. | no | +| `ErrorMessage` | If an error was encountered, the text of the error. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `node_decommissioned` + +An event of type `node_decommissioned` is recorded when a node is marked as +decommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_decommissioning` + +An event of type `node_decommissioning` is recorded when a node is marked as +decommissioning. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_join` + +An event of type `node_join` is recorded when a node joins the cluster. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_recommissioned` + +An event of type `node_recommissioned` is recorded when a decommissioning node is +recommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_restart` + +An event of type `node_restart` is recorded when an existing node rejoins the cluster +after being offline. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_connection_timeout` + +An event of type `node_shutdown_connection_timeout` is recorded when SQL connections remain open +during shutdown, after waiting for the server.shutdown.connections.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still open after waiting for the client to close them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.connections.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_transaction_timeout` + +An event of type `node_shutdown_transaction_timeout` is recorded when SQL transactions remain open +during shutdown, after waiting for the server.shutdown.transactions.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still running SQL transactions after waiting for the client to end them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.transactions.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `tenant_shared_service_start` + +An event of type `tenant_shared_service_start` is recorded when a tenant server +is started inside the same process as the KV layer. + + +| Field | Description | Sensitive | +|--|--|--| +| `OK` | Whether the startup was successful. | no | +| `ErrorText` | If the startup failed, the text of the error. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +### `tenant_shared_service_stop` + +An event of type `tenant_shared_service_stop` is recorded when a tenant server +is shut down inside the same process as the KV layer. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +## Debugging events + +Events in this category pertain to debugging operations performed by +operators or (more commonly) Cockroach Labs employees. These operations can +e.g. directly access and mutate internal state, breaking system invariants. + +Events in this category are logged to the `OPS` channel. + + +### `debug_recover_replica` + +An event of type `debug_recover_replica` is recorded when unsafe loss of quorum recovery is performed. + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `StoreID` | | no | +| `SurvivorReplicaID` | | no | +| `UpdatedReplicaID` | | no | +| `StartKey` | | yes | +| `EndKey` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +### `debug_send_kv_batch` + +An event of type `debug_send_kv_batch` is recorded when an arbitrary KV BatchRequest is submitted +to the cluster via the `debug send-kv-batch` CLI command. + + +| Field | Description | Sensitive | +|--|--|--| +| `BatchRequest` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +## Health events + +Events in this category pertain to the health of one or more servers. + +Events in this category are logged to the `HEALTH` channel. + + +### `runtime_stats` + +An event of type `runtime_stats` is recorded every 10 seconds as server health metrics. + + +| Field | Description | Sensitive | +|--|--|--| +| `MemRSSBytes` | The process resident set size. Expressed as bytes. | no | +| `GoroutineCount` | The number of goroutines. | no | +| `MemStackSysBytes` | The stack system memory used. Expressed as bytes. | no | +| `GoAllocBytes` | The memory allocated by Go. Expressed as bytes. | no | +| `GoTotalBytes` | The total memory allocated by Go but not released. Expressed as bytes. | no | +| `GoStatsStaleness` | The staleness of the Go memory statistics. Expressed in seconds. | no | +| `HeapFragmentBytes` | The amount of heap fragmentation. Expressed as bytes. | no | +| `HeapReservedBytes` | The amount of heap reserved. Expressed as bytes. | no | +| `HeapReleasedBytes` | The amount of heap released. Expressed as bytes. | no | +| `CGoAllocBytes` | The memory allocated outside of Go. Expressed as bytes. | no | +| `CGoTotalBytes` | The total memory allocated outside of Go but not released. Expressed as bytes. | no | +| `CGoCallRate` | The total number of calls outside of Go over time. Expressed as operations per second. | no | +| `CPUUserPercent` | The user CPU percentage. | no | +| `CPUSysPercent` | The system CPU percentage. | no | +| `GCPausePercent` | The GC pause percentage. | no | +| `GCRunCount` | The total number of GC runs. | no | +| `NetHostRecvBytes` | The bytes received on all network interfaces since this process started. | no | +| `NetHostSendBytes` | The bytes sent on all network interfaces since this process started. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Job events + +Events in this category pertain to long-running jobs that are orchestrated by +a node's job registry. These system processes can create and/or modify stored +objects during the course of their execution. + +A job might choose to emit multiple events during its execution when +transitioning from one "state" to another. +Egs: IMPORT/RESTORE will emit events on job creation and successful +completion. If the job fails, events will be emitted on job creation, +failure, and successful revert. + +Events in this category are logged to the `OPS` channel. + + +### `import` + +An event of type `import` is recorded when an import job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `restore` + +An event of type `restore` is recorded when a restore job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +## Miscellaneous SQL events + +Events in this category report miscellaneous SQL events. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own system.eventlog table. + +Events in this category are logged to the `DEV` channel. + + +### `set_cluster_setting` + +An event of type `set_cluster_setting` is recorded when a cluster setting is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `set_tenant_cluster_setting` + +An event of type `set_tenant_cluster_setting` is recorded when a cluster setting override +is changed, either for another tenant or for all tenants. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | +| `TenantId` | The target Tenant ID. Empty if targeting all tenants. | no | +| `AllTenants` | Whether the override applies to all tenants. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +## SQL Access Audit Events + +Events in this category are generated when a table has been +marked as audited via `ALTER TABLE ... EXPERIMENTAL_AUDIT SET`. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SENSITIVE_ACCESS` channel. + + +### `admin_query` + +An event of type `admin_query` is recorded when a user with admin privileges (the user +is directly or indirectly a member of the admin role) executes a query. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `role_based_audit_event` + +An event of type `role_based_audit_event` is an audit event recorded when an executed query belongs to a user whose role +membership(s) correspond to any role that is enabled to emit an audit log via the sql.log.user_audit +cluster setting. + + +| Field | Description | Sensitive | +|--|--|--| +| `Role` | The configured audit role that emitted this log. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sensitive_table_access` + +An event of type `sensitive_table_access` is recorded when an access is performed to +a table marked as audited. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table being audited. | yes | +| `AccessMode` | How the table was accessed (r=read / rw=read/write). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +## SQL Execution Log + +Events in this category report executed queries. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `query_execute` + +An event of type `query_execute` is recorded when a query is executed, +and the cluster setting `sql.log.all_statements.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +## SQL Logical Schema Changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the SQL logical +schema. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SQL_SCHEMA` channel. + + +### `alter_database_add_region` + +An event of type `alter_database_add_region` is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | yes | +| `RegionName` | The region being added. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_drop_region` + +AlterDatabaseAddRegion is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | yes | +| `RegionName` | The region being dropped. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_placement` + +An event of type `alter_database_placement` is recorded when the database placement is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | yes | +| `Placement` | The new placement policy. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_primary_region` + +An event of type `alter_database_primary_region` is recorded when a primary region is added/modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | yes | +| `PrimaryRegionName` | The new primary region. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_set_zone_config_extension` + +An event of type `alter_database_set_zone_config_extension` is recorded when a zone config extension is changed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `alter_database_survival_goal` + +An event of type `alter_database_survival_goal` is recorded when the survival goal is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | yes | +| `SurvivalGoal` | The new survival goal | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_function_options` + +An event of type `alter_function_options` is recorded when a user-defined function's options are +altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the affected function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_index` + +An event of type `alter_index` is recorded when an index is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | yes | +| `IndexName` | The name of the affected index. | yes | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_index_visible` + +AlterIndex is recorded when an index visibility is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | yes | +| `IndexName` | The name of the affected index. | yes | +| `NotVisible` | Set true if index is not visible. NOTE: THIS FIELD IS DEPRECATED in favor of invisibility. | no | +| `Invisibility` | The new invisibility of the affected index. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_sequence` + +An event of type `alter_sequence` is recorded when a sequence is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_table` + +An event of type `alter_table` is recorded when a table is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update, if any. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_type` + +EventAlterType is recorded when a user-defined type is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_column` + +An event of type `comment_on_column` is recorded when a column is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected column. | yes | +| `ColumnName` | The affected column. | yes | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_constraint` + +An event of type `comment_on_constraint` is recorded when an constraint is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected constraint. | yes | +| `ConstraintName` | The name of the affected constraint. | yes | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_database` + +CommentOnTable is recorded when a database is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_index` + +An event of type `comment_on_index` is recorded when an index is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | yes | +| `IndexName` | The name of the affected index. | yes | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_schema` + + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | Name of the affected schema. | yes | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_table` + +An event of type `comment_on_table` is recorded when a table is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `convert_to_schema` + +An event of type `convert_to_schema` is recorded when a database is converted to a schema. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database being converted to a schema. | yes | +| `NewDatabaseParent` | The name of the parent database for the new schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_database` + +An event of type `create_database` is recorded when a database is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the new database. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_function` + +An event of type `create_function` is recorded when a user-defined function is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the created function. | yes | +| `IsReplace` | If the new function is a replace of an existing function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_index` + +An event of type `create_index` is recorded when an index is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the new index. | yes | +| `IndexName` | The name of the new index. | yes | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_schema` + +An event of type `create_schema` is recorded when a schema is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the new schema. | yes | +| `Owner` | The name of the owner for the new schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_sequence` + +An event of type `create_sequence` is recorded when a sequence is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the new sequence. | yes | +| `Owner` | The name of the owner for the new sequence. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_statistics` + +An event of type `create_statistics` is recorded when statistics are collected for a +table. + +Events of this type are only collected when the cluster setting +`sql.stats.post_events.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table for which the statistics were created. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_table` + +An event of type `create_table` is recorded when a table is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the new table. | yes | +| `Owner` | The name of the owner for the new table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_type` + +An event of type `create_type` is recorded when a user-defined type is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the new type. | yes | +| `Owner` | The name of the owner for the new type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_view` + +An event of type `create_view` is recorded when a view is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the new view. | yes | +| `Owner` | The name of the owner of the new view. | yes | +| `ViewQuery` | The SQL selection clause used to define the view. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_database` + +An event of type `drop_database` is recorded when a database is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | +| `DroppedSchemaObjects` | The names of the schemas dropped by a cascade operation. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_function` + +An event of type `drop_function` is recorded when a user-defined function is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the created function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_index` + +An event of type `drop_index` is recorded when an index is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | yes | +| `IndexName` | The name of the affected index. | yes | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_schema` + +An event of type `drop_schema` is recorded when a schema is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_sequence` + +An event of type `drop_sequence` is recorded when a sequence is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_table` + +An event of type `drop_table` is recorded when a table is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_type` + +An event of type `drop_type` is recorded when a user-defined type is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_view` + +An event of type `drop_view` is recorded when a view is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the affected view. | yes | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `finish_schema_change` + +An event of type `finish_schema_change` is recorded when a previously initiated schema +change has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to complete. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `finish_schema_change_rollback` + +An event of type `finish_schema_change_rollback` is recorded when a previously +initiated schema change rollback has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to rollback. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `force_delete_table_data_entry` + + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_database` + +An event of type `rename_database` is recorded when a database is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The old name of the affected database. | yes | +| `NewDatabaseName` | The new name of the affected database. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_function` + +An event of type `rename_function` is recorded when a user-defined function is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The old name of the affected function. | yes | +| `NewFunctionName` | The new name of the affected function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_schema` + +An event of type `rename_schema` is recorded when a schema is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The old name of the affected schema. | yes | +| `NewSchemaName` | The new name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_table` + +An event of type `rename_table` is recorded when a table, sequence or view is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The old name of the affected table. | yes | +| `NewTableName` | The new name of the affected table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_type` + +An event of type `rename_type` is recorded when a user-defined type is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The old name of the affected type. | yes | +| `NewTypeName` | The new name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `reverse_schema_change` + +An event of type `reverse_schema_change` is recorded when an in-progress schema change +encounters a problem and is reversed. + + +| Field | Description | Sensitive | +|--|--|--| +| `Error` | The error encountered that caused the schema change to be reversed. The specific format of the error is variable and can change across releases without warning. | yes | +| `SQLSTATE` | The SQLSTATE code for the error. | no | +| `LatencyNanos` | The amount of time the schema change job took before being reverted. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `set_schema` + +An event of type `set_schema` is recorded when a table, view, sequence or type's schema is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorName` | The old name of the affected descriptor. | yes | +| `NewDescriptorName` | The new name of the affected descriptor. | yes | +| `DescriptorType` | The descriptor type being changed (table, view, sequence, type). | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `truncate_table` + +An event of type `truncate_table` is recorded when a table is truncated. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_delete_descriptor` + +An event of type `unsafe_delete_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_delete_descriptor(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | yes | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_delete_namespace_entry` + +An event of type `unsafe_delete_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_delete_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | yes | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_upsert_descriptor` + +An event of type `unsafe_upsert_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_upsert_descriptor(). + + +| Field | Description | Sensitive | +|--|--|--| +| `PreviousDescriptor` | | yes | +| `NewDescriptor` | | yes | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_upsert_namespace_entry` + +An event of type `unsafe_upsert_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_upsert_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | yes | +| `PreviousID` | | no | +| `Force` | | no | +| `FailedValidation` | | no | +| `ValidationErrors` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +## SQL Privilege changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the privilege +grants for stored objects. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `PRIVILEGES` channel. + + +### `alter_database_owner` + +An event of type `alter_database_owner` is recorded when a database's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database being affected. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_default_privileges` + +An event of type `alter_default_privileges` is recorded when default privileges are changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | +| `RoleName` | Either role_name should be populated or for_all_roles should be true. The role having its default privileges altered. | yes | +| `ForAllRoles` | Identifies if FOR ALL ROLES is used. | no | +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `alter_function_owner` + +AlterTableOwner is recorded when the owner of a user-defined function is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The name of the affected user-defined function. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_schema_owner` + +An event of type `alter_schema_owner` is recorded when a schema's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_table_owner` + +An event of type `alter_table_owner` is recorded when the owner of a table, view or sequence is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected object. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_type_owner` + +An event of type `alter_type_owner` is recorded when the owner of a user-defiend type is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `change_database_privilege` + +An event of type `change_database_privilege` is recorded when privileges are +added to / removed from a user for a database object. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_function_privilege` + + + +| Field | Description | Sensitive | +|--|--|--| +| `FuncName` | The name of the affected function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_schema_privilege` + +An event of type `change_schema_privilege` is recorded when privileges are added to / +removed from a user for a schema object. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_table_privilege` + +An event of type `change_table_privilege` is recorded when privileges are added to / removed +from a user for a table, sequence or view object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_type_privilege` + +An event of type `change_type_privilege` is recorded when privileges are added to / +removed from a user for a type object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +## SQL Session events + +Events in this category report SQL client connections +and sessions. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SESSIONS` channel. + + +### `client_authentication_failed` + +An event of type `client_authentication_failed` is reported when a client session +did not authenticate successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Reason` | The reason for the authentication failure. See below for possible values for type `AuthFailReason`. | no | +| `Detail` | The detailed error for the authentication failure. | partially | +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_info` + +An event of type `client_authentication_info` is reported for intermediate +steps during the authentication process. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used, once known. | no | +| `Info` | The authentication progress message. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_ok` + +An event of type `client_authentication_ok` is reported when a client session +was authenticated successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_connection_end` + +An event of type `client_connection_end` is reported when a client connection +is closed. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_connection_start` + +An event of type `client_connection_start` is reported when a client connection +is established. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_session_end` + +An event of type `client_session_end` is reported when a client session +is completed. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +## SQL Slow Query Log + +Events in this category report slow query execution. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_PERF` channel. + + +### `large_row` + +An event of type `large_row` is recorded when a statement tries to write a row larger than +cluster setting `sql.guardrails.max_row_size_log` to the database. Multiple +LargeRow events will be recorded for statements writing multiple large rows. +LargeRow events are recorded before the transaction commits, so in the case +of transaction abort there will not be a corresponding row in the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query` + +An event of type `slow_query` is recorded when a query triggers the "slow query" condition. + +As of this writing, the condition requires: +- the cluster setting `sql.log.slow_query.latency_threshold` +set to a non-zero value, AND +- EITHER of the following conditions: +- the actual age of the query exceeds the configured threshold; AND/OR +- the query performs a full table/index scan AND the cluster setting +`sql.log.slow_query.experimental_full_table_scans.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit` + +An event of type `txn_rows_read_limit` is recorded when a transaction tries to read more rows than +cluster setting `sql.defaults.transaction_rows_read_log`. There will only be +a single record for a single transaction (unless it is retried) even if there +are more statement within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit` + +An event of type `txn_rows_written_limit` is recorded when a transaction tries to write more rows +than cluster setting `sql.defaults.transaction_rows_written_log`. There will +only be a single record for a single transaction (unless it is retried) even +if there are more mutation statements within the transaction that haven't +been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL Slow Query Log (Internal) + +Events in this category report slow query execution by +internal executors, i.e., when CockroachDB internally issues +SQL statements. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_INTERNAL_PERF` channel. + + +### `large_row_internal` + +An event of type `large_row_internal` is recorded when an internal query tries to write a row +larger than cluster settings `sql.guardrails.max_row_size_log` or +`sql.guardrails.max_row_size_err` to the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query_internal` + +An event of type `slow_query_internal` is recorded when a query triggers the "slow query" condition, +and the cluster setting `sql.log.slow_query.internal_queries.enabled` is +set. +See the documentation for the event type `slow_query` for details about +the "slow query" condition. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit_internal` + +An event of type `txn_rows_read_limit_internal` is recorded when an internal transaction tries to +read more rows than cluster setting `sql.defaults.transaction_rows_read_log` +or `sql.defaults.transaction_rows_read_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit_internal` + +An event of type `txn_rows_written_limit_internal` is recorded when an internal transaction tries to +write more rows than cluster setting +`sql.defaults.transaction_rows_written_log` or +`sql.defaults.transaction_rows_written_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL User and Role operations + +Events in this category pertain to SQL statements that modify the +properties of users and roles. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `USER_ADMIN` channel. + + +### `alter_role` + +An event of type `alter_role` is recorded when a role is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | +| `Options` | The options set on the user/role. | no | +| `SetInfo` | Information corresponding to an ALTER ROLE SET statement. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_role` + +An event of type `create_role` is recorded when a role is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the new user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_role` + +An event of type `drop_role` is recorded when a role is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `grant_role` + +An event of type `grant_role` is recorded when a role is granted. + + +| Field | Description | Sensitive | +|--|--|--| +| `GranteeRoles` | The roles being granted to. | yes | +| `Members` | The roles being granted. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `password_hash_converted` + +An event of type `password_hash_converted` is recorded when the password credentials +are automatically converted server-side. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the user/role whose credentials have been converted. | yes | +| `OldMethod` | The previous hash method. | no | +| `NewMethod` | The new hash method. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Storage telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `level_stats` + +An event of type `level_stats` contains per-level statistics for an LSM. + + +| Field | Description | Sensitive | +|--|--|--| +| `Level` | level is the level ID in a LSM (e.g. level(L0) == 0, etc.) | no | +| `NumFiles` | num_files is the number of files in the level (gauge). | no | +| `SizeBytes` | size_bytes is the size of the level, in bytes (gauge). | no | +| `Score` | score is the compaction score of the level (gauge). | no | +| `BytesIn` | bytes_in is the number of bytes written to this level (counter). | no | +| `BytesIngested` | bytes_ingested is the number of bytes ingested into this level (counter). | no | +| `BytesMoved` | bytes_moved is the number of bytes moved into this level via a move-compaction (counter). | no | +| `BytesRead` | bytes_read is the number of bytes read from this level, during compactions (counter). | no | +| `BytesCompacted` | bytes_compacted is the number of bytes written to this level during compactions (counter). | no | +| `BytesFlushed` | bytes flushed is the number of bytes flushed to this level. This value is always zero for levels other than L0 (counter). | no | +| `TablesCompacted` | tables_compacted is the count of tables compacted into this level (counter). | no | +| `TablesFlushed` | tables_flushed is the count of tables flushed into this level (counter). | no | +| `TablesIngested` | tables_ingested is the count of tables ingested into this level (counter). | no | +| `TablesMoved` | tables_moved is the count of tables moved into this level via move-compactions (counter). | no | +| `NumSublevels` | num_sublevel is the count of sublevels for the level. This value is always zero for levels other than L0 (gauge). | no | + + + +### `store_stats` + +An event of type `store_stats` contains per store stats. + +Note that because stats are scoped to the lifetime of the process, counters +(and certain gauges) will be reset across node restarts. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeId` | node_id is the ID of the node. | no | +| `StoreId` | store_id is the ID of the store. | no | +| `Levels` | levels is a nested message containing per-level statistics. | yes | +| `CacheSize` | cache_size is the size of the cache for the store, in bytes (gauge). | no | +| `CacheCount` | cache_count is the number of items in the cache (gauge). | no | +| `CacheHits` | cache_hits is the number of cache hits (counter). | no | +| `CacheMisses` | cache_misses is the number of cache misses (counter). | no | +| `CompactionCountDefault` | compaction_count_default is the count of default compactions (counter). | no | +| `CompactionCountDeleteOnly` | compaction_count_delete_only is the count of delete-only compactions (counter). | no | +| `CompactionCountElisionOnly` | compaction_count_elision_only is the count of elision-only compactions (counter). | no | +| `CompactionCountMove` | compaction_count_move is the count of move-compactions (counter). | no | +| `CompactionCountRead` | compaction_count_read is the count of read-compactions (counter). | no | +| `CompactionCountRewrite` | compaction_count_rewrite is the count of rewrite-compactions (counter). | no | +| `CompactionNumInProgress` | compactions_num_in_progress is the number of compactions in progress (gauge). | no | +| `CompactionMarkedFiles` | compaction_marked_files is the count of files marked for compaction (gauge). | no | +| `FlushCount` | flush_count is the number of flushes (counter). | no | +| `FlushIngestCount` | | no | +| `FlushIngestTableCount` | | no | +| `FlushIngestTableBytes` | | no | +| `IngestCount` | ingest_count is the number of successful ingest operations (counter). | no | +| `MemtableSize` | memtable_size is the total size allocated to all memtables and (large) batches, in bytes (gauge). | no | +| `MemtableCount` | memtable_count is the count of memtables (gauge). | no | +| `MemtableZombieCount` | memtable_zombie_count is the count of memtables no longer referenced by the current DB state, but still in use by an iterator (gauge). | no | +| `MemtableZombieSize` | memtable_zombie_size is the size, in bytes, of all zombie memtables (gauge). | no | +| `WalLiveCount` | wal_live_count is the count of live WAL files (gauge). | no | +| `WalLiveSize` | wal_live_size is the size, in bytes, of live data in WAL files. With WAL recycling, this value is less than the actual on-disk size of the WAL files (gauge). | no | +| `WalObsoleteCount` | wal_obsolete_count is the count of obsolete WAL files (gauge). | no | +| `WalObsoleteSize` | wal_obsolete_size is the size of obsolete WAL files, in bytes (gauge). | no | +| `WalPhysicalSize` | wal_physical_size is the size, in bytes, of the WAL files on disk (gauge). | no | +| `WalBytesIn` | wal_bytes_in is the number of logical bytes written to the WAL (counter). | no | +| `WalBytesWritten` | wal_bytes_written is the number of bytes written to the WAL (counter). | no | +| `TableObsoleteCount` | table_obsolete_count is the number of tables which are no longer referenced by the current DB state or any open iterators (gauge). | no | +| `TableObsoleteSize` | table_obsolete_size is the size, in bytes, of obsolete tables (gauge). | no | +| `TableZombieCount` | table_zombie_count is the number of tables no longer referenced by the current DB state, but are still in use by an open iterator (gauge). | no | +| `TableZombieSize` | table_zombie_size is the size, in bytes, of zombie tables (gauge). | no | +| `RangeKeySetsCount` | range_key_sets_count is the approximate count of internal range key sets in the store. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `captured_index_usage_stats` + +An event of type `captured_index_usage_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `TotalReadCount` | TotalReadCount is the number of times the index has been read. | no | +| `LastRead` | LastRead is the timestamp at which the index was last read. | no | +| `TableID` | TableID is the ID of the table on which the index was created. This is same as descpb.TableID and is unique within the cluster. | no | +| `IndexID` | IndexID is the ID of the index within the scope of the given table. | no | +| `DatabaseName` | DatabaseName is the name of the database in which the index was created. | no | +| `TableName` | TableName is the name of the table on which the index was created. | no | +| `IndexName` | IndexName is the name of the index within the scope of the given table. | no | +| `IndexType` | IndexType is the type of the index. Index types include "primary" and "secondary". | no | +| `IsUnique` | IsUnique indicates if the index has a UNIQUE constraint. | no | +| `IsInverted` | IsInverted indicates if the index is an inverted index. | no | +| `CreatedAt` | CreatedAt is the timestamp at which the index was created. | no | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `changefeed_emitted_bytes` + +An event of type `changefeed_emitted_bytes` is an event representing the bytes emitted by a changefeed over an interval. + + +| Field | Description | Sensitive | +|--|--|--| +| `JobId` | The job id for enterprise changefeeds. | no | +| `EmittedBytes` | The number of bytes emitted. | no | +| `EmittedMessages` | The number of messages emitted. | no | +| `LoggingInterval` | The time period in nanoseconds between emitting telemetry events of this type (per-aggregator). | no | +| `Closing` | Flag to indicate that the changefeed is closing. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | + +### `changefeed_failed` + +An event of type `changefeed_failed` is an event for any Changefeed failure since the plan hook +was triggered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FailureType` | The reason / environment with which the changefeed failed (ex: connection_closed, changefeed_behind) | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | + +### `create_changefeed` + +An event of type `create_changefeed` is an event for any CREATE CHANGEFEED query that +successfully starts running. Failed CREATE statements will show up as +ChangefeedFailed events. + + +| Field | Description | Sensitive | +|--|--|--| +| `Transformation` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | + +### `hot_ranges_stats` + +An event of type `hot_ranges_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `Qps` | | no | +| `DatabaseName` | DatabaseName is the name of the database in which the index was created. | yes | +| `TableName` | TableName is the name of the table on which the index was created. | yes | +| `IndexName` | IndexName is the name of the index within the scope of the given table. | yes | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | yes | +| `LeaseholderNodeID` | LeaseholderNodeID indicates the Node ID that is the current leaseholder for the given range. | no | +| `WritesPerSecond` | Writes per second is the recent number of keys written per second on this range. | no | +| `ReadsPerSecond` | Reads per second is the recent number of keys read per second on this range. | no | +| `WriteBytesPerSecond` | Write bytes per second is the recent number of bytes written per second on this range. | no | +| `ReadBytesPerSecond` | Read bytes per second is the recent number of bytes read per second on this range. | no | +| `CPUTimePerSecond` | CPU time per second is the recent cpu usage in nanoseconds of this range. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `m_v_c_c_iterator_stats` + +Internal storage iteration statistics for a single execution. + + +| Field | Description | Sensitive | +|--|--|--| +| `StepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `StepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `BlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `BlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `KeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `ValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | + + + +### `recovery_event` + +An event of type `recovery_event` is an event that is logged on every invocation of BACKUP, +RESTORE, and on every BACKUP schedule creation, with the appropriate subset +of fields populated depending on the type of event. This event is is also +logged whenever a BACKUP and RESTORE job completes or fails. + + +| Field | Description | Sensitive | +|--|--|--| +| `RecoveryType` | RecoveryType is the type of recovery described by this event, which is one of - backup - scheduled_backup - create_schedule - restore

It can also be a job event corresponding to the recovery, which is one of - backup_job - scheduled_backup_job - restore_job | no | +| `TargetScope` | TargetScope is the largest scope of the targets that the user is backing up or restoring based on the following order: table < schema < database < full cluster. | no | +| `IsMultiregionTarget` | IsMultiregionTarget is true if any of the targets contain objects with multi-region primitives. | no | +| `TargetCount` | TargetCount is the number of targets the in the BACKUP/RESTORE. | no | +| `DestinationSubdirType` | DestinationSubdirType is - latest: if using the latest subdir - standard: if using a date-based subdir - custom: if using a custom subdir that's not date-based | no | +| `DestinationStorageTypes` | DestinationStorageTypes are the types of storage that the user is backing up to or restoring from. | no | +| `DestinationAuthTypes` | DestinationAuthTypes are the types of authentication methods that the user is using to access the destination storage. | no | +| `IsLocalityAware` | IsLocalityAware indicates if the BACKUP or RESTORE is locality aware. | no | +| `AsOfInterval` | AsOfInterval is the time interval in nanoseconds between the statement timestamp and the timestamp resolved by the AS OF SYSTEM TIME expression. The interval is expressed in nanoseconds. | no | +| `WithRevisionHistory` | WithRevisionHistory is true if the BACKUP includes revision history. | no | +| `HasEncryptionPassphrase` | HasEncryptionPassphrase is true if the user provided an encryption passphrase to encrypt/decrypt their backup. | no | +| `KMSType` | KMSType is the type of KMS the user is using to encrypt/decrypt their backup. | no | +| `KMSCount` | KMSCount is the number of KMS the user is using. | no | +| `Options` | Options contain all the names of the options specified by the user in the BACKUP or RESTORE statement. For options that are accompanied by a value, only those with non-empty values will be present.

It's important to note that there are no option values anywhere in the event payload. Future changes to telemetry should refrain from adding values to the payload unless they are properly redacted. | no | +| `DebugPauseOn` | DebugPauseOn is the type of event that the restore should pause on for debugging purposes. Currently only "error" is supported. | no | +| `JobID` | JobID is the ID of the BACKUP/RESTORE job. | no | +| `ResultStatus` | ResultStatus indicates whether the job succeeded or failed. | no | +| `ErrorText` | ErrorText is the text of the error that caused the job to fail. | partially | +| `RecurringCron` | RecurringCron is the crontab for the incremental backup. | no | +| `FullBackupCron` | FullBackupCron is the crontab for the full backup. | no | +| `CustomFirstRunTime` | CustomFirstRunTime is the timestamp for the user configured first run time. Expressed as nanoseconds since the Unix epoch. | no | +| `OnExecutionFailure` | OnExecutionFailure describes the desired behavior if the schedule fails to execute. | no | +| `OnPreviousRunning` | OnPreviousRunning describes the desired behavior if the previously scheduled BACKUP is still running. | no | +| `IgnoreExistingBackup` | IgnoreExistingBackup is true iff the BACKUP schedule should still be created even if a backup is already present in its destination. | no | +| `ApplicationName` | The application name for the session where recovery event was created. | no | +| `NumRows` | NumRows is the number of rows successfully imported, backed up or restored. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `sampled_exec_stats` + +An event of type `sampled_exec_stats` contains execution statistics that apply to both statements +and transactions. These stats as a whole are collected using a sampling approach. +These exec stats are meant to contain the same fields as ExecStats in +apps_stats.proto but are for a single execution rather than aggregated executions. +Fields in this struct should be updated in sync with apps_stats.proto. + + +| Field | Description | Sensitive | +|--|--|--| +| `NetworkBytes` | NetworkBytes collects the number of bytes sent over the network. | no | +| `MaxMemUsage` | MaxMemUsage collects the maximum memory usage that occurred on a node. | no | +| `ContentionTime` | ContentionTime collects the time in seconds statements in the transaction spent contending. | no | +| `NetworkMessages` | NetworkMessages collects the number of messages that were sent over the network. | no | +| `MaxDiskUsage` | MaxDiskUsage collects the maximum temporary disk usage that occurred. This is set in cases where a query had to spill to disk, e.g. when performing a large sort where not all of the tuples fit in memory. | no | +| `CPUSQLNanos` | CPUSQLNanos collects the CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `MVCCIteratorStats` | Internal storage iteration statistics. | yes | + + + +### `sampled_query` + +An event of type `sampled_query` is the SQL query event logged to the telemetry channel. It +contains common SQL event/execution details. + + +| Field | Description | Sensitive | +|--|--|--| +| `SkippedQueries` | skipped_queries indicate how many SQL statements were not considered for sampling prior to this one. If the field is omitted, or its value is zero, this indicates that no statement was omitted since the last event. | no | +| `CostEstimate` | Cost of the query as estimated by the optimizer. | no | +| `Distribution` | The distribution of the DistSQL query plan (local, full, or partial). | no | +| `PlanGist` | The query's plan gist bytes as a base64 encoded string. | no | +| `SessionID` | SessionID is the ID of the session that initiated the query. | no | +| `Database` | Name of the database that initiated the query. | no | +| `StatementID` | Statement ID of the query. | no | +| `TransactionID` | Transaction ID of the query. | no | +| `MaxFullScanRowsEstimate` | Maximum number of rows scanned by a full scan, as estimated by the optimizer. | no | +| `TotalScanRowsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer. | no | +| `OutputRowsEstimate` | The number of rows output by the query, as estimated by the optimizer. | no | +| `StatsAvailable` | Whether table statistics were available to the optimizer when planning the query. | no | +| `NanosSinceStatsCollected` | The maximum number of nanoseconds that have passed since stats were collected on any table scanned by this query. | no | +| `BytesRead` | The number of bytes read from disk. | no | +| `RowsRead` | The number of rows read from disk. | no | +| `RowsWritten` | The number of rows written. | no | +| `InnerJoinCount` | The number of inner joins in the query plan. | no | +| `LeftOuterJoinCount` | The number of left (or right) outer joins in the query plan. | no | +| `FullOuterJoinCount` | The number of full outer joins in the query plan. | no | +| `SemiJoinCount` | The number of semi joins in the query plan. | no | +| `AntiJoinCount` | The number of anti joins in the query plan. | no | +| `IntersectAllJoinCount` | The number of intersect all joins in the query plan. | no | +| `ExceptAllJoinCount` | The number of except all joins in the query plan. | no | +| `HashJoinCount` | The number of hash joins in the query plan. | no | +| `CrossJoinCount` | The number of cross joins in the query plan. | no | +| `IndexJoinCount` | The number of index joins in the query plan. | no | +| `LookupJoinCount` | The number of lookup joins in the query plan. | no | +| `MergeJoinCount` | The number of merge joins in the query plan. | no | +| `InvertedJoinCount` | The number of inverted joins in the query plan. | no | +| `ApplyJoinCount` | The number of apply joins in the query plan. | no | +| `ZigZagJoinCount` | The number of zig zag joins in the query plan. | no | +| `ContentionNanos` | The duration of time in nanoseconds that the query experienced contention. | no | +| `Regions` | The regions of the nodes where SQL processors ran. | no | +| `NetworkBytesSent` | The number of network bytes sent by nodes for this query. | no | +| `MaxMemUsage` | The maximum amount of memory usage by nodes for this query. | no | +| `MaxDiskUsage` | The maximum amount of disk usage by nodes for this query. | no | +| `KVBytesRead` | The number of bytes read at the KV layer for this query. | no | +| `KVPairsRead` | The number of key-value pairs read at the KV layer for this query. | no | +| `KVRowsRead` | The number of rows read at the KV layer for this query. | no | +| `NetworkMessages` | The number of network messages sent by nodes for this query. | no | +| `IndexRecommendations` | Generated index recommendations for this query. | no | +| `ScanCount` | The number of scans in the query plan. | no | +| `ScanWithStatsCount` | The number of scans using statistics (including forecasted statistics) in the query plan. | no | +| `ScanWithStatsForecastCount` | The number of scans using forecasted statistics in the query plan. | no | +| `TotalScanRowsWithoutForecastsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer without using forecasts. | no | +| `NanosSinceStatsForecasted` | The greatest quantity of nanoseconds that have passed since the forecast time (or until the forecast time, if it is in the future, in which case it will be negative) for any table with forecasted stats scanned by this query. | no | +| `Indexes` | The list of indexes used by this query. | no | +| `CpuTimeNanos` | Collects the cumulative CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `KvGrpcCalls` | The number of grpc calls done to get data form KV nodes | no | +| `KvTimeNanos` | Cumulated time spent waiting for a KV request. This includes disk IO time and potentially network time (if any of the keys are not local). | no | +| `ServiceLatencyNanos` | The time to service the query, from start of parse to end of execute. | no | +| `OverheadLatencyNanos` | The difference between service latency and the sum of parse latency + plan latency + run latency . | no | +| `RunLatencyNanos` | The time to run the query and fetch or compute the result rows. | no | +| `PlanLatencyNanos` | The time to transform the AST into a logical query plan. | no | +| `IdleLatencyNanos` | The time between statement executions in a transaction | no | +| `ParseLatencyNanos` | The time to transform the SQL string into an abstract syntax tree (AST). | no | +| `MvccStepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccStepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccBlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `MvccBlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `MvccKeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `SchemaChangerMode` | SchemaChangerMode is the mode that was used to execute the schema change, if any. | no | +| `SQLInstanceIDs` | SQLInstanceIDs is a list of all the SQL instances used in this statement's execution. | no | +| `StatementFingerprintID` | Statement fingerprint ID of the query. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sampled_transaction` + +An event of type `sampled_transaction` is the event logged to telemetry at the end of transaction execution. + + +| Field | Description | Sensitive | +|--|--|--| +| `User` | User is the user account that triggered the transaction. The special usernames `root` and `node` are not considered sensitive. | depends | +| `ApplicationName` | ApplicationName is the application name for the session where the transaction was executed. This is included in the event to ease filtering of logging output by application. | no | +| `TxnCounter` | TxnCounter is the sequence number of the SQL transaction inside its session. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `TransactionID` | TransactionID is the id of the transaction. | no | +| `Committed` | Committed indicates if the transaction committed successfully. We want to include this value even if it is false. | no | +| `ImplicitTxn` | ImplicitTxn indicates if the transaction was an implicit one. We want to include this value even if it is false. | no | +| `StartTimeUnixNanos` | StartTimeUnixNanos is the time the transaction was started. Expressed as unix time in nanoseconds. | no | +| `EndTimeUnixNanos` | EndTimeUnixNanos the time the transaction finished (either committed or aborted). Expressed as unix time in nanoseconds. | no | +| `ServiceLatNanos` | ServiceLatNanos is the time to service the whole transaction, from start to end of execution. | no | +| `SQLSTATE` | SQLSTATE is the SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | ErrorText is the text of the error if any. | partially | +| `NumRetries` | NumRetries is the number of time when the txn was retried automatically by the server. | no | +| `LastAutoRetryReason` | LastAutoRetryReason is a string containing the reason for the last automatic retry. | partially | +| `NumRows` | NumRows is the total number of rows returned across all statements. | no | +| `RetryLatNanos` | RetryLatNanos is the amount of time spent retrying the transaction. | no | +| `CommitLatNanos` | CommitLatNanos is the amount of time spent committing the transaction after all statement operations. | no | +| `IdleLatNanos` | IdleLatNanos is the amount of time spent waiting for the client to send statements while the transaction is open. | no | +| `BytesRead` | BytesRead is the number of bytes read from disk. | no | +| `RowsRead` | RowsRead is the number of rows read from disk. | no | +| `RowsWritten` | RowsWritten is the number of rows written to disk. | no | +| `SampledExecStats` | SampledExecStats is a nested field containing execution statistics. This field will be omitted if the stats were not sampled. | yes | +| `SkippedTransactions` | SkippedTransactions is the number of transactions that were skipped as part of sampling prior to this one. We only count skipped transactions when telemetry logging is enabled and the sampling mode is set to "transaction". | no | +| `TransactionFingerprintID` | TransactionFingerprintID is the fingerprint ID of the transaction. This can be used to find the transaction in the console. | no | +| `StatementFingerprintIDs` | StatementFingerprintIDs is an array of statement fingerprint IDs belonging to this transaction. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_descriptor` + +An event of type `schema_descriptor` is an event for schema telemetry, whose purpose is +to take periodic snapshots of the cluster's SQL schema and publish them in +the telemetry log channel. For all intents and purposes, the data in such a +snapshot can be thought of the outer join of certain system tables: +namespace, descriptor, and at some point perhaps zones, etc. + +Snapshots are too large to conveniently be published as a single log event, +so instead they're broken down into SchemaDescriptor events which +contain the data in one record of this outer join projection. These events +are prefixed by a header (a SchemaSnapshotMetadata event). + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of the snapshot that this event is part of. | no | +| `ParentDatabaseID` | ParentDatabaseID matches the same key column in system.namespace. | no | +| `ParentSchemaID` | ParentSchemaID matches the same key column in system.namespace. | no | +| `Name` | Name matches the same key column in system.namespace. | no | +| `DescID` | DescID matches the 'id' column in system.namespace and system.descriptor. | no | +| `Desc` | Desc matches the 'descriptor' column in system.descriptor. Some contents of the descriptor may be redacted to prevent leaking PII. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_snapshot_metadata` + +An event of type `schema_snapshot_metadata` is an event describing a schema snapshot, which +is a set of SchemaDescriptor messages sharing the same SnapshotID. + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of this snapshot. | no | +| `NumRecords` | NumRecords is how many SchemaDescriptor events are in the snapshot. | no | +| `AsOfTimestamp` | AsOfTimestamp is when the snapshot was taken. This is equivalent to the timestamp given in the AS OF SYSTEM TIME clause when querying the namespace and descriptor tables in the system database. Expressed as nanoseconds since the Unix epoch. | no | +| `Errors` | Errors records any errors encountered when post-processing this snapshot, which includes the redaction of any potential PII. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Zone config events + +Events in this category pertain to zone configuration changes on +the SQL schema or system ranges. + +When zone configs apply to individual tables or other objects in a +SQL logical schema, they are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these zone config events are preserved +in each tenant's own `system.eventlog` table. + +When they apply to cluster-level ranges (e.g., the system zone config), +they are stored in the system tenant's own `system.eventlog` table. + +Events in this category are logged to the `OPS` channel. + + +### `remove_zone_config` + +An event of type `remove_zone_config` is recorded when a zone config is removed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `set_zone_config` + +An event of type `set_zone_config` is recorded when a zone config is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `ResolvedOldConfig` | The string representation of the resolved old zone config. This is not necessarily the same as the zone config that was previously set -- as it includes the resolved values of the zone config options. In other words, a zone config that hasn't been properly "set" yet (and inherits from its parent) will have a resolved_old_config that has details of the values it inherits from its parent. This is particularly useful to get a proper diff between the old and new zone config. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + + + + +## Enumeration types + +### `AuthFailReason` + +AuthFailReason is the inventory of possible reasons for an +authentication failure. + + +| Value | Textual alias in code or documentation | Description | +|--|--|--| +| 0 | UNKNOWN | is reported when the reason is unknown. | +| 1 | USER_RETRIEVAL_ERROR | occurs when there was an internal error accessing the principals. | +| 2 | USER_NOT_FOUND | occurs when the principal is unknown. | +| 3 | LOGIN_DISABLED | occurs when the user does not have LOGIN privileges. | +| 4 | METHOD_NOT_FOUND | occurs when no HBA rule matches or the method does not exist. | +| 5 | PRE_HOOK_ERROR | occurs when the authentication handshake encountered a protocol error. | +| 6 | CREDENTIALS_INVALID | occurs when the client-provided credentials were invalid. | +| 7 | CREDENTIALS_EXPIRED | occur when the credentials provided by the client are expired. | +| 8 | NO_REPLICATION_ROLEOPTION | occurs when the connection requires a replication role option, but the user does not have it. | + + + diff --git a/src/current/_includes/cockroach-generated/release-23.2/logformats.md b/src/current/_includes/cockroach-generated/release-23.2/logformats.md new file mode 100644 index 00000000000..89580c9fc15 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-23.2/logformats.md @@ -0,0 +1,382 @@ + +The supported log output formats are documented below. + + +- [`crdb-v1`](#format-crdb-v1) + +- [`crdb-v1-count`](#format-crdb-v1-count) + +- [`crdb-v1-tty`](#format-crdb-v1-tty) + +- [`crdb-v1-tty-count`](#format-crdb-v1-tty-count) + +- [`crdb-v2`](#format-crdb-v2) + +- [`crdb-v2-tty`](#format-crdb-v2-tty) + +- [`json`](#format-json) + +- [`json-compact`](#format-json-compact) + +- [`json-fluent`](#format-json-fluent) + +- [`json-fluent-compact`](#format-json-fluent-compact) + + + +## Format `crdb-v1` + + +This is a legacy file format used from CockroachDB v1.0. + +Each log entry is emitted using a common prefix, described below, followed by: + +- The logging context tags enclosed between `[` and `]`, if any. It is possible + for this to be omitted if there were no context tags. +- Optionally, a counter column, if the option 'show-counter' is enabled. See below for details. +- the text of the log entry. + +Beware that the text of the log entry can span multiple lines. +The following caveats apply: + +- The text of the log entry can start with text enclosed between `[` and `]`. + If there were no logging tags to start with, it is not possible to distinguish between + logging context tag information and a `[...]` string in the main text of the + log entry. This means that this format is ambiguous. + + To remove this ambiguity, you can use the option 'show-counter'. + +- The text of the log entry can embed arbitrary application-level strings, + including strings that represent log entries. In particular, an accident + of implementation can cause the common entry prefix (described below) + to also appear on a line of its own, as part of the payload of a previous + log entry. There is no automated way to recognize when this occurs. + Care must be taken by a human observer to recognize these situations. + +- The log entry parser provided by CockroachDB to read log files is faulty + and is unable to recognize the aforementioned pitfall; nor can it read + entries larger than 64KiB successfully. Generally, use of this internal + log entry parser is discouraged for entries written with this format. + +See the newer format `crdb-v2` for an alternative +without these limitations. + +### Header lines + +At the beginning of each file, a header is printed using a similar format as +regular log entries. This header reports when the file was created, +which parameters were used to start the server, the server identifiers +if known, and other metadata about the running process. + +- This header appears to be logged at severity `INFO` (with an `I` prefix + at the start of the line) even though it does not really have a severity. +- The header is printed unconditionally even when a filter is configured to + omit entries at the `INFO` level. + +### Common log entry prefix + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker tags counter + +Reminder, the tags may be omitted; and the counter is only printed if the option +'show-counter' is specified. + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (omitted if zero for use by tests). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. | +| line | The line number where the entry originated. | +| marker | Redactability marker ` + redactableIndicator + ` (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. May be absent. | +| counter | The entry counter. Only included if 'show-counter' is enabled. | + +The redactability marker can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. + +If the marker ` + redactableIndicator + ` is present, the remainder of the log entry +contains delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `show-counter` | Whether to include the counter column in the line header. Without it, the format may be ambiguous due to the optionality of tags. | +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v1-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: none` + + +## Format `crdb-v1-tty` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: false` +- `colors: auto` + + +## Format `crdb-v1-tty-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: auto` + + +## Format `crdb-v2` + +This is the main file format used from CockroachDB v21.1. + +Each log entry is emitted using a common prefix, described below, +followed by the text of the log entry. + +### Entry format + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker [tags...] counter cont + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (zero when cannot be determined). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. Also see below. | +| line | The line number where the entry originated. | +| marker | Redactability marker "⋮" (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. See below. | +| counter | The optional entry counter (see below for details). | +| cont | Continuation mark for structured and multi-line entries. See below. | + +The `chan@` prefix before the file name indicates the logging channel, +and is omitted if the channel is `DEV`. + +The file name may be prefixed by the string `(gostd) ` to indicate +that the log entry was produced inside the Go standard library, instead +of a CockroachDB component. Entry parsers must be configured to ignore this prefix +when present. + +`marker` can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. +If the marker "⋮" is present, the remainder of the log entry +contains delimiters (‹...›) +around fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +when log redaction is requested. + +The logging `tags` are enclosed between square brackets `[...]`, +and the syntax `[-]` is used when there are no logging tags +associated with the log entry. + +`counter` is numeric, and is incremented for every +log entry emitted to this sink. (There is thus one counter sequence per +sink.) For entries that do not have a counter value +associated (e.g., header entries in file sinks), the counter position +in the common prefix is empty: `tags` is then +followed by two ASCII space characters, instead of one space; the `counter`, +and another space. The presence of the two ASCII spaces indicates +reliably that no counter was present. + +`cont` is a format/continuation indicator: + +| Continuation indicator | ASCII | Description | +|------------------------|-------|--| +| space | 0x32 | Start of an unstructured entry. | +| equal sign, "=" | 0x3d | Start of a structured entry. | +| exclamation mark, "!" | 0x21 | Start of an embedded stack trace. | +| plus sign, "+" | 0x2b | Continuation of a multi-line entry. The payload contains a newline character at this position. | +| vertical bar | 0x7c | Continuation of a large entry. | + +### Examples + +Example single-line unstructured entry: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 started with engine type ‹2› +~~~ + +Example multi-line unstructured entry: + +~~~ +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 node startup completed: +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 +CockroachDB node starting at 2021-01-16 21:49 (took 0.0s) +~~~ + +Example structured entry: + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventType":"node_restart"} +~~~ + +Example long entries broken up into multiple lines: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.... +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 |aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +~~~ + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventTy... +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 |pe":"node_restart"} +~~~ + +### Backward-compatibility notes + +Entries in this format can be read by most `crdb-v1` log parsers, +in particular the one included in the DB console and +also the [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +facility. + +However, implementers of previous version parsers must +understand that the logging tags field is now always +included, and the lack of logging tags is included +by a tag string set to `[-]`. + +Likewise, the entry counter is now also always included, +and there is a special character after `counter` +to indicate whether the remainder of the line is a +structured entry, or a continuation of a previous entry. + +Finally, in the previous format, structured entries +were prefixed with the string `Structured entry: `. In +the new format, they are prefixed by the `=` continuation +indicator. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v2-tty` + +This format name is an alias for 'crdb-v2' with +the following format option defaults: + +- `colors: auto` + + +## Format `json` + +This format emits log entries as a JSON payload. + +The JSON object is guaranteed to not contain unescaped newlines +or other special characters, and the entry as a whole is followed +by a newline character. This makes the format suitable for +processing over a stream unambiguously. + +Each entry contains at least the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `tag` | `tag` | (Only if the option `fluent-tag: true` is given.) A Fluent tag for the event, formed by the process name and the logging channel. | +| `d` | `datetime` | The pretty-printed date/time of the event timestamp, if enabled via options. | +| `f` | `file` | The name of the source file where the event was emitted. | +| `g` | `goroutine` | The identifier of the goroutine where the event was emitted. | +| `l` | `line` | The line number where the event was emitted in the source. | +| `r` | `redactable` | Whether the payload is redactable (see below for details). | +| `t` | `timestamp` | The timestamp at which the event was emitted on the logging channel. | +| `v` | `version` | The binary version with which the event was generated. | + + +After a couple of *header* entries written at the beginning of each log sink, +all subsequent log entries also contain the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `C` | `channel` | The name of the logging channel where the event was sent. | +| `sev` | `severity` | The severity of the event. | +| `c` | `channel_numeric` | The numeric identifier for the logging channel where the event was sent. | +| `n` | `entry_counter` | The entry number on this logging sink, relative to the last process restart. | +| `s` | `severity_numeric` | The numeric value of the severity of the event. | + + +Additionally, the following fields are conditionally present: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `N` | `node_id` | The node ID where the event was generated, once known. Only reported for single-tenant or KV servers. | +| `x` | `cluster_id` | The cluster ID where the event was generated, once known. Only reported for single-tenant of KV servers. | +| `q` | `instance_id` | The SQL instance ID where the event was generated, once known. | +| `T` | `tenant_id` | The SQL tenant ID where the event was generated, once known. | +| `V` | `tenant_name` | The SQL virtual cluster where the event was generated, once known. | +| `tags` | `tags` | The logging context tags for the entry, if there were context tags. | +| `message` | `message` | For unstructured events, the flat text payload. | +| `event` | `event` | The logging event, if structured (see below for details). | +| `stacks` | `stacks` | Goroutine stacks, for fatal events. | + +When an entry is structured, the `event` field maps to a dictionary +whose structure is one of the documented structured events. See the [reference documentation](eventlog.html) +for structured events for a list of possible payloads. + +When the entry is marked as `redactable`, the `tags`, `message`, and/or `event` payloads +contain delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `datetime-format` | The format to use for the `datetime` field. The value can be one of `none`, `iso8601`/`rfc3339` (synonyms), or `rfc1123`. Default is `none`. | +| `datetime-timezone` | The timezone to use for the `datetime` field. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | +| `tag-style` | The tags to include in the envelope. The value can be `compact` (one letter tags) or `verbose` (long-form tags). Default is `verbose`. | +| `fluent-tag` | Whether to produce an additional field called `tag` for Fluent compatibility. Default is `false`. | + + + +## Format `json-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: false` +- `tag-style: compact` + + +## Format `json-fluent` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: verbose` + + +## Format `json-fluent-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: compact` + + diff --git a/src/current/_includes/cockroach-generated/release-23.2/logging.md b/src/current/_includes/cockroach-generated/release-23.2/logging.md new file mode 100644 index 00000000000..8b628dc2dd9 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-23.2/logging.md @@ -0,0 +1,179 @@ +## Logging levels (severities) + +### INFO + +The `INFO` severity is used for informational messages that do not +require action. + +### WARNING + +The `WARNING` severity is used for situations which may require special handling, +where normal operation is expected to resume automatically. + +### ERROR + +The `ERROR` severity is used for situations that require special handling, +where normal operation could not proceed as expected. +Other operations can continue mostly unaffected. + +### FATAL + +The `FATAL` severity is used for situations that require an immedate, hard +server shutdown. A report is also sent to telemetry if telemetry +is enabled. + + +## Logging channels + +### `DEV` + +The `DEV` channel is used during development to collect log +details useful for troubleshooting that fall outside the +scope of other channels. It is also the default logging +channel for events not associated with a channel. + +This channel is special in that there are no constraints as to +what may or may not be logged on it. Conversely, users in +production deployments are invited to not collect `DEV` logs in +centralized logging facilities, because they likely contain +sensitive operational data. +See [Configure logs](configure-logs.html#dev-channel). + +### `OPS` + +The `OPS` channel is used to report "point" operational events, +initiated by user operators or automation: + + - Operator or system actions on server processes: process starts, + stops, shutdowns, crashes (if they can be logged), + including each time: command-line parameters, current version being run + - Actions that impact the topology of a cluster: node additions, + removals, decommissions, etc. + - Job-related initiation or termination + - [Cluster setting](cluster-settings.html) changes + - [Zone configuration](configure-replication-zones.html) changes + +### `HEALTH` + +The `HEALTH` channel is used to report "background" operational +events, initiated by CockroachDB or reporting on automatic processes: + + - Current resource usage, including critical resource usage + - Node-node connection events, including connection errors and + gossip details + - Range and table leasing events + - Up- and down-replication, range unavailability + +### `STORAGE` + +The `STORAGE` channel is used to report low-level storage +layer events (RocksDB/Pebble). + +### `SESSIONS` + +The `SESSIONS` channel is used to report client network activity when enabled via +the `server.auth_log.sql_connections.enabled` and/or +`server.auth_log.sql_sessions.enabled` [cluster setting](cluster-settings.html): + + - Connections opened/closed + - Authentication events: logins, failed attempts + - Session and query cancellation + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_SCHEMA` + +The `SQL_SCHEMA` channel is used to report changes to the +SQL logical schema, excluding privilege and ownership changes +(which are reported separately on the `PRIVILEGES` channel) and +zone configuration changes (which go to the `OPS` channel). + +This includes: + + - Database/schema/table/sequence/view/type creation + - Adding/removing/changing table columns + - Changing sequence parameters + +`SQL_SCHEMA` events generally comprise changes to the schema that affect the +functional behavior of client apps using stored objects. + +### `USER_ADMIN` + +The `USER_ADMIN` channel is used to report changes +in users and roles, including: + + - Users added/dropped + - Changes to authentication credentials (e.g., passwords, validity, etc.) + - Role grants/revocations + - Role option grants/revocations + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `PRIVILEGES` + +The `PRIVILEGES` channel is used to report data +authorization changes, including: + + - Privilege grants/revocations on database, objects, etc. + - Object ownership changes + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SENSITIVE_ACCESS` + +The `SENSITIVE_ACCESS` channel is used to report SQL +data access to sensitive data: + + - Data access audit events (when table audit is enabled via + [ALTER TABLE ... EXPERIMENTAL_AUDIT](alter-table.html#experimental_audit)) + - Data access audit events (when role-based audit is enabled via + [`sql.log.user_audit` cluster setting](role-based-audit-logging.html#syntax-of-audit-settings)) + - SQL statements executed by users with the admin role + - Operations that write to system tables + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_EXEC` + +The `SQL_EXEC` channel is used to report SQL execution on +behalf of client connections: + + - Logical SQL statement executions (when enabled via the + `sql.log.all_statements.enabled` [cluster setting](cluster-settings.html)) + - uncaught Go panic errors during the execution of a SQL statement. + +### `SQL_PERF` + +The `SQL_PERF` channel is used to report SQL executions +that are marked as "out of the ordinary" +to facilitate performance investigations. +This includes the SQL "slow query log". + +Arguably, this channel overlaps with `SQL_EXEC`. +However, we keep both channels separate for backward compatibility +with versions prior to v21.1, where the corresponding events +were redirected to separate files. + +### `SQL_INTERNAL_PERF` + +The `SQL_INTERNAL_PERF` channel is like the `SQL_PERF` channel, but is aimed at +helping developers of CockroachDB itself. It exists as a separate +channel so as to not pollute the `SQL_PERF` logging output with +internal troubleshooting details. + +### `TELEMETRY` + +The `TELEMETRY` channel reports telemetry events. Telemetry events describe +feature usage within CockroachDB and anonymizes any application- +specific data. + +### `KV_DISTRIBUTION` + +The `KV_DISTRIBUTION` channel is used to report data distribution events, such as moving +replicas between stores in the cluster, or adding (removing) replicas to +ranges. + diff --git a/src/current/_includes/cockroach-generated/release-23.2/settings/settings.html b/src/current/_includes/cockroach-generated/release-23.2/settings/settings.html new file mode 100644 index 00000000000..561114c87ca --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-23.2/settings/settings.html @@ -0,0 +1,293 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingTypeDefaultDescriptionSupported Deployments
admission.disk_bandwidth_tokens.elastic.enabled
booleantruewhen true, and provisioned bandwidth for the disk corresponding to a store is configured, tokens for elastic work will be limited if disk bandwidth becomes a bottleneckDedicated/Self-Hosted
admission.epoch_lifo.enabled
booleanfalsewhen true, epoch-LIFO behavior is enabled when there is significant delay in admissionServerless/Dedicated/Self-Hosted
admission.epoch_lifo.epoch_closing_delta_duration
duration5msthe delta duration before closing an epoch, for epoch-LIFO admission control orderingServerless/Dedicated/Self-Hosted
admission.epoch_lifo.epoch_duration
duration100msthe duration of an epoch, for epoch-LIFO admission control orderingServerless/Dedicated/Self-Hosted
admission.epoch_lifo.queue_delay_threshold_to_switch_to_lifo
duration105msthe queue delay encountered by a (tenant,priority) for switching to epoch-LIFO orderingServerless/Dedicated/Self-Hosted
admission.kv.enabled
booleantruewhen true, work performed by the KV layer is subject to admission controlDedicated/Self-Hosted
admission.sql_kv_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a KV response is subject to admission controlServerless/Dedicated/Self-Hosted
admission.sql_sql_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a DistSQL response is subject to admission controlServerless/Dedicated/Self-Hosted
bulkio.backup.deprecated_full_backup_with_subdir.enabled
booleanfalsewhen true, a backup command with a user specified subdirectory will create a full backup at the subdirectory if no backup already exists at that subdirectoryServerless/Dedicated/Self-Hosted
bulkio.backup.file_size
byte size128 MiBtarget size for individual data files produced during BACKUPServerless/Dedicated/Self-Hosted
bulkio.backup.read_timeout
duration5m0samount of time after which a read attempt is considered timed out, which causes the backup to failServerless/Dedicated/Self-Hosted
bulkio.backup.read_with_priority_after
duration1m0samount of time since the read-as-of time above which a BACKUP should use priority when retrying readsServerless/Dedicated/Self-Hosted
physical_replication.consumer.minimum_flush_interval
(alias: bulkio.stream_ingestion.minimum_flush_interval)
duration5sthe minimum timestamp between flushes; flushes may still occur if internal buffers fill upDedicated/Self-Hosted
changefeed.aggregator.flush_jitter
float0jitter aggregator flushes as a fraction of min_checkpoint_frequency. This setting has no effect if min_checkpoint_frequency is set to 0.Serverless/Dedicated/Self-Hosted
changefeed.backfill.concurrent_scan_requests
integer0number of concurrent scan requests per node issued during a backfillServerless/Dedicated/Self-Hosted
changefeed.backfill.scan_request_size
integer524288the maximum number of bytes returned by each scan requestServerless/Dedicated/Self-Hosted
changefeed.balance_range_distribution.enabled
(alias: changefeed.balance_range_distribution.enable)
booleanfalseif enabled, the ranges are balanced equally among all nodes. Note that this is supported only in export mode with initial_scan=only.Serverless/Dedicated/Self-Hosted
changefeed.batch_reduction_retry.enabled
(alias: changefeed.batch_reduction_retry_enabled)
booleanfalseif true, kafka changefeeds upon erroring on an oversized batch will attempt to resend the messages with progressively lower batch sizesServerless/Dedicated/Self-Hosted
changefeed.event_consumer_worker_queue_size
integer16if changefeed.event_consumer_workers is enabled, this setting sets the maxmimum number of events which a worker can bufferServerless/Dedicated/Self-Hosted
changefeed.event_consumer_workers
integer0the number of workers to use when processing events: <0 disables, 0 assigns a reasonable default, >0 assigns the setting value. for experimental/core changefeeds and changefeeds using parquet format, this is disabledServerless/Dedicated/Self-Hosted
changefeed.fast_gzip.enabled
booleantrueuse fast gzip implementationServerless/Dedicated/Self-Hosted
changefeed.frontier_highwater_lag_checkpoint_threshold
duration10m0scontrols the maximum the high-water mark is allowed to lag behind the leading spans of the frontier before per-span checkpointing is enabled; if 0, checkpointing due to high-water lag is disabledServerless/Dedicated/Self-Hosted
changefeed.memory.per_changefeed_limit
byte size512 MiBcontrols amount of data that can be buffered per changefeedServerless/Dedicated/Self-Hosted
changefeed.min_highwater_advance
duration0sminimum amount of time the changefeed high water mark must advance for it to be eligible for checkpointing; Default of 0 will checkpoint every time frontier advances, as long as the rate of checkpointing keeps up with the rate of frontier changesServerless/Dedicated/Self-Hosted
changefeed.node_throttle_config
stringspecifies node level throttling configuration for all changefeeedsServerless/Dedicated/Self-Hosted
changefeed.protect_timestamp.max_age
duration96h0m0sfail the changefeed if the protected timestamp age exceeds this threshold; 0 disables expirationServerless/Dedicated/Self-Hosted
changefeed.protect_timestamp_interval
duration10m0scontrols how often the changefeed forwards its protected timestamp to the resolved timestampServerless/Dedicated/Self-Hosted
changefeed.schema_feed.read_with_priority_after
duration1m0sretry with high priority if we were not able to read descriptors for too long; 0 disablesServerless/Dedicated/Self-Hosted
changefeed.sink_io_workers
integer0the number of workers used by changefeeds when sending requests to the sink (currently the batching versions of webhook, pubsub, and kafka sinks that are enabled by changefeed.new_<sink type>_sink_enabled only): <0 disables, 0 assigns a reasonable default, >0 assigns the setting valueServerless/Dedicated/Self-Hosted
cloudstorage.azure.concurrent_upload_buffers
integer1controls the number of concurrent buffers that will be used by the Azure client when uploading chunks.Each buffer can buffer up to cloudstorage.write_chunk.size of memory during an uploadServerless/Dedicated/Self-Hosted
cloudstorage.http.custom_ca
stringcustom root CA (appended to system's default CAs) for verifying certificates when interacting with HTTPS storageServerless/Dedicated/Self-Hosted
cloudstorage.timeout
duration10m0sthe timeout for import/export storage operationsServerless/Dedicated/Self-Hosted
cluster.auto_upgrade.enabled
booleantruedisable automatic cluster version upgrade until resetServerless/Dedicated/Self-Hosted
cluster.organization
stringorganization nameServerless/Dedicated/Self-Hosted (read-only)
cluster.preserve_downgrade_option
stringdisable (automatic or manual) cluster version upgrade from the specified version until resetServerless/Dedicated/Self-Hosted
diagnostics.active_query_dumps.enabled
booleantrueexperimental: enable dumping of anonymized active queries to disk when node is under memory pressureServerless/Dedicated/Self-Hosted (read-only)
diagnostics.forced_sql_stat_reset.interval
duration2h0m0sinterval after which the reported SQL Stats are reset even if not collected by telemetry reporter. It has a max value of 24H.Serverless/Dedicated/Self-Hosted
diagnostics.memory_monitoring_dumps.enabled
booleantrueenable dumping of memory monitoring state at the same time as heap profiles are takenServerless/Dedicated/Self-Hosted (read-only)
diagnostics.reporting.enabled
booleantrueenable reporting diagnostic metrics to cockroach labs, but is ignored for Trial or Free licensesServerless/Dedicated/Self-Hosted
diagnostics.reporting.interval
duration1h0m0sinterval at which diagnostics data should be reportedServerless/Dedicated/Self-Hosted
enterprise.license
stringthe encoded cluster licenseServerless/Dedicated/Self-Hosted (read-only)
external.graphite.endpoint
stringif nonempty, push server metrics to the Graphite or Carbon server at the specified host:portServerless/Dedicated/Self-Hosted
external.graphite.interval
duration10sthe interval at which metrics are pushed to Graphite (if enabled)Serverless/Dedicated/Self-Hosted
feature.backup.enabled
booleantrueset to true to enable backups, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.changefeed.enabled
booleantrueset to true to enable changefeeds, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.export.enabled
booleantrueset to true to enable exports, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.import.enabled
booleantrueset to true to enable imports, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.restore.enabled
booleantrueset to true to enable restore, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.schema_change.enabled
booleantrueset to true to enable schema changes, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.stats.enabled
booleantrueset to true to enable CREATE STATISTICS/ANALYZE, false to disable; default is trueServerless/Dedicated/Self-Hosted
jobs.retention_time
duration336h0m0sthe amount of time for which records for completed jobs are retainedServerless/Dedicated/Self-Hosted
kv.allocator.lease_rebalance_threshold
float0.05minimum fraction away from the mean a store's lease count can be before it is considered for lease-transfersDedicated/Self-Hosted
kv.allocator.load_based_lease_rebalancing.enabled
booleantrueset to enable rebalancing of range leases based on load and latencyDedicated/Self-Hosted
kv.allocator.load_based_rebalancing
enumerationleases and replicaswhether to rebalance based on the distribution of load across stores [off = 0, leases = 1, leases and replicas = 2]Dedicated/Self-Hosted
kv.allocator.load_based_rebalancing.objective
enumerationcpuwhat objective does the cluster use to rebalance; if set to `qps` the cluster will attempt to balance qps among stores, if set to `cpu` the cluster will attempt to balance cpu usage among stores [qps = 0, cpu = 1]Dedicated/Self-Hosted
kv.allocator.load_based_rebalancing_interval
duration1m0sthe rough interval at which each store will check for load-based lease / replica rebalancing opportunitiesDedicated/Self-Hosted
kv.allocator.qps_rebalance_threshold
float0.1minimum fraction away from the mean a store's QPS (such as queries per second) can be before it is considered overfull or underfullDedicated/Self-Hosted
kv.allocator.range_rebalance_threshold
float0.05minimum fraction away from the mean a store's range count can be before it is considered overfull or underfullDedicated/Self-Hosted
kv.allocator.store_cpu_rebalance_threshold
float0.1minimum fraction away from the mean a store's cpu usage can be before it is considered overfull or underfullDedicated/Self-Hosted
kv.bulk_io_write.max_rate
byte size1.0 TiBthe rate limit (bytes/sec) to use for writes to disk on behalf of bulk io opsDedicated/Self-Hosted
kv.bulk_sst.max_allowed_overage
byte size64 MiBif positive, allowed size in excess of target size for SSTs from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryDedicated/Self-Hosted
kv.bulk_sst.target_size
byte size16 MiBtarget size for SSTs emitted from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryServerless/Dedicated/Self-Hosted (read-only)
kv.closed_timestamp.follower_reads.enabled
(alias: kv.closed_timestamp.follower_reads_enabled)
booleantrueallow (all) replicas to serve consistent historical reads based on closed timestamp informationServerless/Dedicated/Self-Hosted (read-only)
kv.closed_timestamp.lead_for_global_reads_override
duration0sif nonzero, overrides the lead time that global_read ranges use to publish closed timestampsServerless/Dedicated/Self-Hosted (read-only)
kv.closed_timestamp.side_transport_interval
duration200msthe interval at which the closed timestamp side-transport attempts to advance each range's closed timestamp; set to 0 to disable the side-transportServerless/Dedicated/Self-Hosted (read-only)
kv.closed_timestamp.target_duration
duration3sif nonzero, attempt to provide closed timestamp notifications for timestamps trailing cluster time by approximately this durationServerless/Dedicated/Self-Hosted (read-only)
kv.log_range_and_node_events.enabled
booleantrueset to true to transactionally log range events (e.g., split, merge, add/remove voter/non-voter) into system.rangelogand node join and restart events into system.eventologDedicated/Self-Hosted
kv.protectedts.reconciliation.interval
duration5m0sthe frequency for reconciling jobs with protected timestamp recordsServerless/Dedicated/Self-Hosted (read-only)
kv.range_split.by_load.enabled
(alias: kv.range_split.by_load_enabled)
booleantrueallow automatic splits of ranges based on where load is concentratedDedicated/Self-Hosted
kv.range_split.load_cpu_threshold
duration500msthe CPU use per second over which, the range becomes a candidate for load based splittingDedicated/Self-Hosted
kv.range_split.load_qps_threshold
integer2500the QPS over which, the range becomes a candidate for load based splittingDedicated/Self-Hosted
kv.rangefeed.client.stream_startup_rate
integer100controls the rate per second the client will initiate new rangefeed stream for a single range; 0 implies unlimitedServerless/Dedicated/Self-Hosted
kv.rangefeed.closed_timestamp_refresh_interval
duration3sthe interval at which closed-timestamp updatesare delivered to rangefeeds; set to 0 to use kv.closed_timestamp.side_transport_intervalServerless/Dedicated/Self-Hosted (read-only)
kv.rangefeed.enabled
booleanfalseif set, rangefeed registration is enabledServerless/Dedicated/Self-Hosted (read-only)
kv.rangefeed.range_stuck_threshold
duration1m0srestart rangefeeds if they don't emit anything for the specified threshold; 0 disables (kv.rangefeed.closed_timestamp_refresh_interval takes precedence)Serverless/Dedicated/Self-Hosted
kv.replica_circuit_breaker.slow_replication_threshold
duration1m0sduration after which slow proposals trip the per-Replica circuit breaker (zero duration disables breakers)Dedicated/Self-Hosted
kv.replica_stats.addsst_request_size_factor
integer50000the divisor that is applied to addsstable request sizes, then recorded in a leaseholders QPS; 0 means all requests are treated as cost 1Dedicated/Self-Hosted
kv.replication_reports.interval
duration1m0sthe frequency for generating the replication_constraint_stats, replication_stats_report and replication_critical_localities reports (set to 0 to disable)Dedicated/Self-Hosted
kv.snapshot_rebalance.max_rate
byte size32 MiBthe rate limit (bytes/sec) to use for rebalance and upreplication snapshotsDedicated/Self-Hosted
kv.snapshot_receiver.excise.enabled
booleanfalseset to true to use the experimental and unstable excise operation instead of range deletions for KV snapshotsDedicated/Self-Hosted
kv.transaction.max_intents_bytes
integer4194304maximum number of bytes used to track locks in transactionsServerless/Dedicated/Self-Hosted
kv.transaction.max_refresh_spans_bytes
integer4194304maximum number of bytes used to track refresh spans in serializable transactionsServerless/Dedicated/Self-Hosted
kv.transaction.reject_over_max_intents_budget.enabled
booleanfalseif set, transactions that exceed their lock tracking budget (kv.transaction.max_intents_bytes) are rejected instead of having their lock spans imprecisely compressedServerless/Dedicated/Self-Hosted
kvadmission.store.provisioned_bandwidth
byte size0 Bif set to a non-zero value, this is used as the provisioned bandwidth (in bytes/s), for each store. It can be over-ridden on a per-store basis using the --store flagDedicated/Self-Hosted
schedules.backup.gc_protection.enabled
booleantrueenable chaining of GC protection across backups run as part of a scheduleServerless/Dedicated/Self-Hosted
security.ocsp.mode
enumerationoffuse OCSP to check whether TLS certificates are revoked. If the OCSP server is unreachable, in strict mode all certificates will be rejected and in lax mode all certificates will be accepted. [off = 0, lax = 1, strict = 2]Serverless/Dedicated/Self-Hosted
security.ocsp.timeout
duration3stimeout before considering the OCSP server unreachableServerless/Dedicated/Self-Hosted
server.auth_log.sql_connections.enabled
booleanfalseif set, log SQL client connect and disconnect events to the SESSIONS log channel (note: may hinder performance on loaded nodes)Serverless/Dedicated/Self-Hosted
server.auth_log.sql_sessions.enabled
booleanfalseif set, log verbose SQL session authentication events to the SESSIONS log channel (note: may hinder performance on loaded nodes). Session start and end events are always logged regardless of this setting; disable the SESSIONS log channel to suppress them.Serverless/Dedicated/Self-Hosted
server.authentication_cache.enabled
booleantrueenables a cache used during authentication to avoid lookups to system tables when retrieving per-user authentication-related informationServerless/Dedicated/Self-Hosted
server.child_metrics.enabled
booleanfalseenables the exporting of child metrics, additional prometheus time series with extra labelsServerless/Dedicated/Self-Hosted
server.client_cert_expiration_cache.capacity
integer1000the maximum number of client cert expirations storedServerless/Dedicated/Self-Hosted
server.clock.forward_jump_check.enabled
(alias: server.clock.forward_jump_check_enabled)
booleanfalseif enabled, forward clock jumps > max_offset/2 will cause a panicServerless/Dedicated/Self-Hosted
server.clock.persist_upper_bound_interval
duration0sthe interval between persisting the wall time upper bound of the clock. The clock does not generate a wall time greater than the persisted timestamp and will panic if it sees a wall time greater than this value. When cockroach starts, it waits for the wall time to catch-up till this persisted timestamp. This guarantees monotonic wall time across server restarts. Not setting this or setting a value of 0 disables this feature.Serverless/Dedicated/Self-Hosted
server.consistency_check.max_rate
byte size8.0 MiBthe rate limit (bytes/sec) to use for consistency checks; used in conjunction with server.consistency_check.interval to control the frequency of consistency checks. Note that setting this too high can negatively impact performance.Dedicated/Self-Hosted
server.eventlog.enabled
booleantrueif set, logged notable events are also stored in the table system.eventlogServerless/Dedicated/Self-Hosted
server.eventlog.ttl
duration2160h0m0sif nonzero, entries in system.eventlog older than this duration are periodically purgedServerless/Dedicated/Self-Hosted
server.host_based_authentication.configuration
stringhost-based authentication configuration to use during connection authenticationServerless/Dedicated/Self-Hosted
server.hot_ranges_request.node.timeout
duration5m0sthe duration allowed for a single node to return hot range data before the request is cancelled; if set to 0, there is no timeoutServerless/Dedicated/Self-Hosted
server.hsts.enabled
booleanfalseif true, HSTS headers will be sent along with all HTTP requests. The headers will contain a max-age setting of one year. Browsers honoring the header will always use HTTPS to access the DB Console. Ensure that TLS is correctly configured prior to enabling.Serverless/Dedicated/Self-Hosted
server.http.base_path
string/path to redirect the user to upon succcessful loginServerless/Dedicated/Self-Hosted
server.identity_map.configuration
stringsystem-identity to database-username mappingsServerless/Dedicated/Self-Hosted
server.log_gc.max_deletions_per_cycle
integer1000the maximum number of entries to delete on each purge of log-like system tablesServerless/Dedicated/Self-Hosted
server.log_gc.period
duration1h0m0sthe period at which log-like system tables are checked for old entriesServerless/Dedicated/Self-Hosted
server.max_connections_per_gateway
integer-1the maximum number of SQL connections per gateway allowed at a given time (note: this will only limit future connection attempts and will not affect already established connections). Negative values result in unlimited number of connections. Superusers are not affected by this limit.Serverless/Dedicated/Self-Hosted
server.max_open_transactions_per_gateway
integer-1the maximum number of open SQL transactions per gateway allowed at a given time. Negative values result in unlimited number of connections. Superusers are not affected by this limit.Serverless/Dedicated/Self-Hosted
server.oidc_authentication.autologin.enabled
(alias: server.oidc_authentication.autologin)
booleanfalseif true, logged-out visitors to the DB Console will be automatically redirected to the OIDC login endpointServerless/Dedicated/Self-Hosted
server.oidc_authentication.button_text
stringLog in with your OIDC providertext to show on button on DB Console login page to login with your OIDC provider (only shown if OIDC is enabled)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.claim_json_key
stringsets JSON key of principal to extract from payload after OIDC authentication completes (usually email or sid)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.client_id
stringsets OIDC client idServerless/Dedicated/Self-Hosted
server.oidc_authentication.client_secret
stringsets OIDC client secretServerless/Dedicated/Self-Hosted
server.oidc_authentication.enabled
booleanfalseenables or disabled OIDC login for the DB ConsoleServerless/Dedicated/Self-Hosted
server.oidc_authentication.principal_regex
string(.+)regular expression to apply to extracted principal (see claim_json_key setting) to translate to SQL user (golang regex format, must include 1 grouping to extract)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.provider_url
stringsets OIDC provider URL ({provider_url}/.well-known/openid-configuration must resolve)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.redirect_url
stringhttps://localhost:8080/oidc/v1/callbacksets OIDC redirect URL via a URL string or a JSON string containing a required `redirect_urls` key with an object that maps from region keys to URL strings (URLs should point to your load balancer and must route to the path /oidc/v1/callback)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.scopes
stringopenidsets OIDC scopes to include with authentication request (space delimited list of strings, required to start with `openid`)Serverless/Dedicated/Self-Hosted
server.rangelog.ttl
duration720h0m0sif nonzero, entries in system.rangelog older than this duration are periodically purgedDedicated/Self-Hosted
server.redact_sensitive_settings.enabled
booleanfalseenables or disables the redaction of sensitive settings in the output of SHOW CLUSTER SETTINGS and SHOW ALL CLUSTER SETTINGS for users without the MODIFYCLUSTERSETTING privilegeServerless/Dedicated/Self-Hosted
server.shutdown.connections.timeout
(alias: server.shutdown.connection_wait)
duration0sthe maximum amount of time a server waits for all SQL connections to be closed before proceeding with a drain. (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Serverless/Dedicated/Self-Hosted
server.shutdown.initial_wait
(alias: server.shutdown.drain_wait)
duration0sthe amount of time a server waits in an unready state before proceeding with a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting. --drain-wait is to specify the duration of the whole draining process, while server.shutdown.initial_wait is to set the wait time for health probes to notice that the node is not ready.)Serverless/Dedicated/Self-Hosted
server.shutdown.lease_transfer_iteration.timeout
(alias: server.shutdown.lease_transfer_wait)
duration5sthe timeout for a single iteration of the range lease transfer phase of draining (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Dedicated/Self-Hosted
server.shutdown.transactions.timeout
(alias: server.shutdown.query_wait)
duration10sthe timeout for waiting for active transactions to finish during a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Serverless/Dedicated/Self-Hosted
server.time_until_store_dead
duration5m0sthe time after which if there is no new gossiped information about a store, it is considered deadServerless/Dedicated/Self-Hosted
server.user_login.cert_password_method.auto_scram_promotion.enabled
booleantruewhether to automatically promote cert-password authentication to use SCRAMServerless/Dedicated/Self-Hosted
server.user_login.downgrade_scram_stored_passwords_to_bcrypt.enabled
booleantrueif server.user_login.password_encryption=crdb-bcrypt, this controls whether to automatically re-encode stored passwords using scram-sha-256 to crdb-bcryptServerless/Dedicated/Self-Hosted
server.user_login.min_password_length
integer1the minimum length accepted for passwords set in cleartext via SQL. Note that a value lower than 1 is ignored: passwords cannot be empty in any case.Serverless/Dedicated/Self-Hosted
server.user_login.password_encryption
enumerationscram-sha-256which hash method to use to encode cleartext passwords passed via ALTER/CREATE USER/ROLE WITH PASSWORD [crdb-bcrypt = 2, scram-sha-256 = 3]Serverless/Dedicated/Self-Hosted
server.user_login.password_hashes.default_cost.crdb_bcrypt
integer10the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method crdb-bcrypt (allowed range: 4-31)Serverless/Dedicated/Self-Hosted
server.user_login.password_hashes.default_cost.scram_sha_256
integer10610the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method scram-sha-256 (allowed range: 4096-240000000000)Serverless/Dedicated/Self-Hosted
server.user_login.rehash_scram_stored_passwords_on_cost_change.enabled
booleantrueif server.user_login.password_hashes.default_cost.scram_sha_256 differs from, the cost in a stored hash, this controls whether to automatically re-encode stored passwords using scram-sha-256 with the new default costServerless/Dedicated/Self-Hosted
server.user_login.timeout
duration10stimeout after which client authentication times out if some system range is unavailable (0 = no timeout)Serverless/Dedicated/Self-Hosted
server.user_login.upgrade_bcrypt_stored_passwords_to_scram.enabled
booleantrueif server.user_login.password_encryption=scram-sha-256, this controls whether to automatically re-encode stored passwords using crdb-bcrypt to scram-sha-256Serverless/Dedicated/Self-Hosted
server.web_session.purge.ttl
duration1h0m0sif nonzero, entries in system.web_sessions older than this duration are periodically purgedServerless/Dedicated/Self-Hosted
server.web_session.timeout
(alias: server.web_session_timeout)
duration168h0m0sthe duration that a newly created web session will be validServerless/Dedicated/Self-Hosted
spanconfig.bounds.enabled
booleantruedictates whether span config bounds are consulted when serving span configs for secondary tenantsDedicated/Self-Hosted
spanconfig.range_coalescing.system.enabled
(alias: spanconfig.storage_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs, for the ranges specific to the system tenantDedicated/Self-Hosted
spanconfig.range_coalescing.application.enabled
(alias: spanconfig.tenant_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs across all secondary tenant keyspacesDedicated/Self-Hosted
sql.auth.change_own_password.enabled
booleanfalsecontrols whether a user is allowed to change their own password, even if they have no other privilegesServerless/Dedicated/Self-Hosted
sql.auth.grant_option_for_owner.enabled
booleantruedetermines whether the GRANT OPTION for privileges is implicitly given to the owner of an objectServerless/Dedicated/Self-Hosted
sql.auth.grant_option_inheritance.enabled
booleantruedetermines whether the GRANT OPTION for privileges is inherited through role membershipServerless/Dedicated/Self-Hosted
sql.auth.public_schema_create_privilege.enabled
booleantruedetermines whether to grant all users the CREATE privileges on the public schema when it is createdServerless/Dedicated/Self-Hosted
sql.auth.resolve_membership_single_scan.enabled
booleantruedetermines whether to populate the role membership cache with a single scanServerless/Dedicated/Self-Hosted
sql.closed_session_cache.capacity
integer1000the maximum number of sessions in the cacheServerless/Dedicated/Self-Hosted
sql.closed_session_cache.time_to_live
integer3600the maximum time to live, in secondsServerless/Dedicated/Self-Hosted
sql.contention.event_store.capacity
byte size64 MiBthe in-memory storage capacity per-node of contention event storeServerless/Dedicated/Self-Hosted
sql.contention.event_store.duration_threshold
duration0sminimum contention duration to cause the contention events to be collected into crdb_internal.transaction_contention_eventsServerless/Dedicated/Self-Hosted
sql.contention.txn_id_cache.max_size
byte size64 MiBthe maximum byte size TxnID cache will use (set to 0 to disable)Serverless/Dedicated/Self-Hosted
sql.cross_db_fks.enabled
booleanfalseif true, creating foreign key references across databases is allowedServerless/Dedicated/Self-Hosted
sql.cross_db_sequence_owners.enabled
booleanfalseif true, creating sequences owned by tables from other databases is allowedServerless/Dedicated/Self-Hosted
sql.cross_db_sequence_references.enabled
booleanfalseif true, sequences referenced by tables from other databases are allowedServerless/Dedicated/Self-Hosted
sql.cross_db_views.enabled
booleanfalseif true, creating views that refer to other databases is allowedServerless/Dedicated/Self-Hosted
sql.defaults.cost_scans_with_default_col_size.enabled
booleanfalsesetting to true uses the same size for all columns to compute scan cost
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.datestyle
enumerationiso, mdydefault value for DateStyle session setting [iso, mdy = 0, iso, dmy = 1, iso, ymd = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.default_hash_sharded_index_bucket_count
integer16used as bucket count if bucket count is not specified in hash sharded index definition
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.default_int_size
integer8the size, in bytes, of an INT type
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.disallow_full_table_scans.enabled
booleanfalsesetting to true rejects queries that have planned a full table scan
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.distsql
enumerationautodefault distributed SQL execution mode [off = 0, auto = 1, on = 2, always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_alter_column_type.enabled
booleanfalsedefault value for experimental_alter_column_type session setting; enables the use of ALTER COLUMN TYPE for general conversions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_distsql_planning
enumerationoffdefault experimental_distsql_planning mode; enables experimental opt-driven DistSQL planning [off = 0, on = 1]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_enable_unique_without_index_constraints.enabled
booleanfalsedefault value for experimental_enable_unique_without_index_constraints session setting;disables unique without index constraints by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_implicit_column_partitioning.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for the use of implicit column partitioning
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_temporary_tables.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for use of temporary tables by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.foreign_key_cascades_limit
integer10000default value for foreign_key_cascades_limit session setting; limits the number of cascading operations that run as part of a single query
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.idle_in_session_timeout
duration0sdefault value for the idle_in_session_timeout; default value for the idle_in_session_timeout session setting; controls the duration a session is permitted to idle before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.idle_in_transaction_session_timeout
duration0sdefault value for the idle_in_transaction_session_timeout; controls the duration a session is permitted to idle in a transaction before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.implicit_select_for_update.enabled
booleantruedefault value for enable_implicit_select_for_update session setting; enables FOR UPDATE locking during the row-fetch phase of mutation statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.insert_fast_path.enabled
booleantruedefault value for enable_insert_fast_path session setting; enables a specialized insert path
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.intervalstyle
enumerationpostgresdefault value for IntervalStyle session setting [postgres = 0, iso_8601 = 1, sql_standard = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.large_full_scan_rows
float1000default value for large_full_scan_rows session setting which determines the maximum table size allowed for a full scan when disallow_full_table_scans is set to true
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.locality_optimized_partitioned_index_scan.enabled
booleantruedefault value for locality_optimized_partitioned_index_scan session setting; enables searching for rows in the current region before searching remote regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.lock_timeout
duration0sdefault value for the lock_timeout; default value for the lock_timeout session setting; controls the duration a query is permitted to wait while attempting to acquire a lock on a key or while blocking on an existing lock in order to perform a non-locking read on a key; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.on_update_rehome_row.enabled
booleantruedefault value for on_update_rehome_row; enables ON UPDATE rehome_row() expressions to trigger on updates
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.optimizer_use_histograms.enabled
booleantruedefault value for optimizer_use_histograms session setting; enables usage of histograms in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.optimizer_use_multicol_stats.enabled
booleantruedefault value for optimizer_use_multicol_stats session setting; enables usage of multi-column stats in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.override_alter_primary_region_in_super_region.enabled
booleanfalsedefault value for override_alter_primary_region_in_super_region; allows for altering the primary region even if the primary region is a member of a super region
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.override_multi_region_zone_config.enabled
booleanfalsedefault value for override_multi_region_zone_config; allows for overriding the zone configs of a multi-region table or database
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.prefer_lookup_joins_for_fks.enabled
booleanfalsedefault value for prefer_lookup_joins_for_fks session setting; causes foreign key operations to use lookup joins when possible
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.primary_region
stringif not empty, all databases created without a PRIMARY REGION will implicitly have the given PRIMARY REGION
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.reorder_joins_limit
integer8default number of joins to reorder
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.require_explicit_primary_keys.enabled
booleanfalsedefault value for requiring explicit primary keys in CREATE TABLE statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.results_buffer.size
byte size16 KiBdefault size of the buffer that accumulates results for a statement or a batch of statements before they are sent to the client. This can be overridden on an individual connection with the 'results_buffer_size' parameter. Note that auto-retries generally only happen while no results have been delivered to the client, so reducing this size can increase the number of retriable errors a client receives. On the other hand, increasing the buffer size can increase the delay until the client receives the first result row. Updating the setting only affects new connections. Setting to 0 disables any buffering.
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.serial_normalization
enumerationrowiddefault handling of SERIAL in table definitions [rowid = 0, virtual_sequence = 1, sql_sequence = 2, sql_sequence_cached = 3, unordered_rowid = 4]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.statement_timeout
duration0sdefault value for the statement_timeout; default value for the statement_timeout session setting; controls the duration a query is permitted to run before it is canceled; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.stub_catalog_tables.enabled
booleantruedefault value for stub_catalog_tables session setting
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.super_regions.enabled
booleanfalsedefault value for enable_super_regions; allows for the usage of super regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_read_err
integer0the limit for the number of rows read by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_read_log
integer0the threshold for the number of rows read by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_written_err
integer0the limit for the number of rows written by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_written_log
integer0the threshold for the number of rows written by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.use_declarative_schema_changer
enumerationondefault value for use_declarative_schema_changer session setting;disables new schema changer by default [off = 0, on = 1, unsafe = 2, unsafe_always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.vectorize
enumerationondefault vectorize mode [on = 0, on = 2, experimental_always = 3, off = 4]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.zigzag_join.enabled
booleanfalsedefault value for enable_zigzag_join session setting; disallows use of zig-zag join by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.distsql.temp_storage.workmem
byte size64 MiBmaximum amount of memory in bytes a processor can use before falling back to temp storageServerless/Dedicated/Self-Hosted
sql.guardrails.max_row_size_err
byte size512 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an error is returned; use 0 to disableServerless/Dedicated/Self-Hosted
sql.guardrails.max_row_size_log
byte size64 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an event is logged to SQL_PERF (or SQL_INTERNAL_PERF if the mutating statement was internal); use 0 to disableServerless/Dedicated/Self-Hosted
sql.hash_sharded_range_pre_split.max
integer16max pre-split ranges to have when adding hash sharded index to an existing tableServerless/Dedicated/Self-Hosted
sql.index_recommendation.drop_unused_duration
duration168h0m0sthe index unused duration at which we begin to recommend dropping the indexServerless/Dedicated/Self-Hosted
sql.insights.anomaly_detection.enabled
booleantrueenable per-fingerprint latency recording and anomaly detectionServerless/Dedicated/Self-Hosted
sql.insights.anomaly_detection.latency_threshold
duration50msstatements must surpass this threshold to trigger anomaly detection and identificationServerless/Dedicated/Self-Hosted
sql.insights.anomaly_detection.memory_limit
byte size1.0 MiBthe maximum amount of memory allowed for tracking statement latenciesServerless/Dedicated/Self-Hosted
sql.insights.execution_insights_capacity
integer1000the size of the per-node store of execution insightsServerless/Dedicated/Self-Hosted
sql.insights.high_retry_count.threshold
integer10the number of retries a slow statement must have undergone for its high retry count to be highlighted as a potential problemServerless/Dedicated/Self-Hosted
sql.insights.latency_threshold
duration100msamount of time after which an executing statement is considered slow. Use 0 to disable.Serverless/Dedicated/Self-Hosted
sql.log.slow_query.experimental_full_table_scans.enabled
booleanfalsewhen set to true, statements that perform a full table/index scan will be logged to the slow query log even if they do not meet the latency threshold. Must have the slow query log enabled for this setting to have any effect.Serverless/Dedicated/Self-Hosted
sql.log.slow_query.internal_queries.enabled
booleanfalsewhen set to true, internal queries which exceed the slow query log threshold are logged to a separate log. Must have the slow query log enabled for this setting to have any effect.Serverless/Dedicated/Self-Hosted
sql.log.slow_query.latency_threshold
duration0swhen set to non-zero, log statements whose service latency exceeds the threshold to a secondary logger on each nodeServerless/Dedicated/Self-Hosted
sql.log.user_audit
stringuser/role-based audit logging configuration. An enterprise license is required for this cluster setting to take effect.Serverless/Dedicated/Self-Hosted
sql.log.user_audit.reduced_config.enabled
booleanfalseenables logic to compute a reduced audit configuration, computing the audit configuration only once at session start instead of at each SQL event. The tradeoff with the increase in performance (~5%), is that changes to the audit configuration (user role memberships/cluster setting) are not reflected within session. Users will need to start a new session to see these changes in their auditing behaviour.Serverless/Dedicated/Self-Hosted
sql.metrics.index_usage_stats.enabled
booleantruecollect per index usage statisticsServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_reported_stmt_fingerprints
integer100000the maximum number of reported statement fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_reported_txn_fingerprints
integer100000the maximum number of reported transaction fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_stmt_fingerprints
integer100000the maximum number of statement fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_txn_fingerprints
integer100000the maximum number of transaction fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.dump_to_logs.enabled
(alias: sql.metrics.statement_details.dump_to_logs)
booleanfalsedump collected statement statistics to node logs when periodically clearedServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.enabled
booleantruecollect per-statement query statisticsServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.gateway_node.enabled
booleanfalsesave the gateway node for each statement fingerprint. If false, the value will be stored as 0.Serverless/Dedicated/Self-Hosted
sql.metrics.statement_details.index_recommendation_collection.enabled
booleantruegenerate an index recommendation for each fingerprint IDServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.max_mem_reported_idx_recommendations
integer5000the maximum number of reported index recommendation info stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.plan_collection.enabled
booleanfalseperiodically save a logical plan for each fingerprintServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.plan_collection.period
duration5m0sthe time until a new logical plan is collectedServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.threshold
duration0sminimum execution time to cause statement statistics to be collected. If configured, no transaction stats are collected.Serverless/Dedicated/Self-Hosted
sql.metrics.transaction_details.enabled
booleantruecollect per-application transaction statisticsServerless/Dedicated/Self-Hosted
sql.multiple_modifications_of_table.enabled
booleanfalseif true, allow statements containing multiple INSERT ON CONFLICT, UPSERT, UPDATE, or DELETE subqueries modifying the same table, at the risk of data corruption if the same row is modified multiple times by a single statement (multiple INSERT subqueries without ON CONFLICT cannot cause corruption and are always allowed)Serverless/Dedicated/Self-Hosted
sql.multiregion.drop_primary_region.enabled
booleantrueallows dropping the PRIMARY REGION of a database if it is the last regionServerless/Dedicated/Self-Hosted
sql.notices.enabled
booleantrueenable notices in the server/client protocol being sentServerless/Dedicated/Self-Hosted
sql.optimizer.uniqueness_checks_for_gen_random_uuid.enabled
booleanfalseif enabled, uniqueness checks may be planned for mutations of UUID columns updated with gen_random_uuid(); otherwise, uniqueness is assumed due to near-zero collision probabilityServerless/Dedicated/Self-Hosted
sql.schema.telemetry.recurrence
string@weeklycron-tab recurrence for SQL schema telemetry jobServerless/Dedicated/Self-Hosted (read-only)
sql.show_ranges_deprecated_behavior.enabled
booleanfalseif set, SHOW RANGES and crdb_internal.ranges{_no_leases} behave with deprecated pre-v23.1 semantics. NB: the new SHOW RANGES interface has richer WITH options than pre-v23.1 SHOW RANGES.Serverless/Dedicated/Self-Hosted
sql.spatial.experimental_box2d_comparison_operators.enabled
booleanfalseenables the use of certain experimental box2d comparison operatorsServerless/Dedicated/Self-Hosted
sql.stats.activity.persisted_rows.max
integer200000maximum number of rows of statement and transaction activity that will be persisted in the system tablesServerless/Dedicated/Self-Hosted
sql.stats.automatic_collection.enabled
booleantrueautomatic statistics collection modeServerless/Dedicated/Self-Hosted
sql.stats.automatic_collection.fraction_stale_rows
float0.2target fraction of stale rows per table that will trigger a statistics refreshServerless/Dedicated/Self-Hosted
sql.stats.automatic_collection.min_stale_rows
integer500target minimum number of stale rows per table that will trigger a statistics refreshServerless/Dedicated/Self-Hosted
sql.stats.cleanup.recurrence
string@hourlycron-tab recurrence for SQL Stats cleanup jobServerless/Dedicated/Self-Hosted
sql.stats.flush.enabled
booleantrueif set, SQL execution statistics are periodically flushed to diskServerless/Dedicated/Self-Hosted
sql.stats.flush.interval
duration10m0sthe interval at which SQL execution statistics are flushed to disk, this value must be less than or equal to 1 hourServerless/Dedicated/Self-Hosted
sql.stats.forecasts.enabled
booleantruewhen true, enables generation of statistics forecasts by default for all tablesServerless/Dedicated/Self-Hosted
sql.stats.forecasts.max_decrease
float0.3333333333333333the most a prediction is allowed to decrease, expressed as the minimum ratio of the prediction to the lowest prior observationServerless/Dedicated/Self-Hosted
sql.stats.forecasts.min_goodness_of_fit
float0.95the minimum R² (goodness of fit) measurement required from all predictive models to use a forecastServerless/Dedicated/Self-Hosted
sql.stats.forecasts.min_observations
integer3the mimimum number of observed statistics required to produce a statistics forecastServerless/Dedicated/Self-Hosted
sql.stats.histogram_buckets.count
integer200maximum number of histogram buckets to build during table statistics collectionServerless/Dedicated/Self-Hosted
sql.stats.histogram_collection.enabled
booleantruehistogram collection modeServerless/Dedicated/Self-Hosted
sql.stats.histogram_samples.count
integer10000number of rows sampled for histogram construction during table statistics collectionServerless/Dedicated/Self-Hosted
sql.stats.multi_column_collection.enabled
booleantruemulti-column statistics collection modeServerless/Dedicated/Self-Hosted
sql.stats.non_default_columns.min_retention_period
duration24h0m0sminimum retention period for table statistics collected on non-default columnsServerless/Dedicated/Self-Hosted
sql.stats.non_indexed_json_histograms.enabled
booleantrueset to true to collect table statistics histograms on non-indexed JSON columnsServerless/Dedicated/Self-Hosted
sql.stats.persisted_rows.max
integer1000000maximum number of rows of statement and transaction statistics that will be persisted in the system tables before compaction beginsServerless/Dedicated/Self-Hosted
sql.stats.post_events.enabled
booleanfalseif set, an event is logged for every CREATE STATISTICS jobServerless/Dedicated/Self-Hosted
sql.stats.response.max
integer20000the maximum number of statements and transaction stats returned in a CombinedStatements requestServerless/Dedicated/Self-Hosted
sql.stats.response.show_internal.enabled
booleanfalsecontrols if statistics for internal executions should be returned by the CombinedStatements and if internal sessions should be returned by the ListSessions endpoints. These endpoints are used to display statistics on the SQL Activity pagesServerless/Dedicated/Self-Hosted
sql.stats.system_tables.enabled
booleantruewhen true, enables use of statistics on system tables by the query optimizerServerless/Dedicated/Self-Hosted
sql.stats.system_tables_autostats.enabled
booleantruewhen true, enables automatic collection of statistics on system tablesServerless/Dedicated/Self-Hosted
sql.stats.virtual_computed_columns.enabled
booleanfalseset to true to collect table statistics on virtual computed columnsServerless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.enabled
booleanfalsewhen set to true, executed queries will emit an event on the telemetry logging channelServerless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.internal.enabled
booleanfalsewhen set to true, internal queries will be sampled in telemetry loggingServerless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample executions for telemetry, note that it is recommended that this value shares a log-line limit of 10 logs per second on the telemetry pipeline with all other telemetry events. If sampling mode is set to 'transaction', this value is ignored.Serverless/Dedicated/Self-Hosted
sql.telemetry.transaction_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample transactions for telemetry. If sampling mode is set to 'statement', this setting is ignored. In practice, this means that we only sample a transaction if 1/max_event_frequency seconds have elapsed since the last transaction was sampled.Serverless/Dedicated/Self-Hosted
sql.telemetry.transaction_sampling.statement_events_per_transaction.max
integer50the maximum number of statement events to log for every sampled transaction. Note that statements that are logged by force do not adhere to this limit.Serverless/Dedicated/Self-Hosted
sql.temp_object_cleaner.cleanup_interval
duration30m0show often to clean up orphaned temporary objectsServerless/Dedicated/Self-Hosted
sql.temp_object_cleaner.wait_interval
duration30m0show long after creation a temporary object will be cleaned upServerless/Dedicated/Self-Hosted
sql.log.all_statements.enabled
(alias: sql.trace.log_statement_execute)
booleanfalseset to true to enable logging of all executed statementsServerless/Dedicated/Self-Hosted
sql.trace.session_eventlog.enabled
booleanfalseset to true to enable session tracing; note that enabling this may have a negative performance impactServerless/Dedicated/Self-Hosted
sql.trace.stmt.enable_threshold
duration0senables tracing on all statements; statements executing for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting applies to individual statements within a transaction and is therefore finer-grained than sql.trace.txn.enable_thresholdServerless/Dedicated/Self-Hosted
sql.trace.txn.enable_threshold
duration0senables tracing on all transactions; transactions open for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting is coarser-grained than sql.trace.stmt.enable_threshold because it applies to all statements within a transaction as well as client communication (e.g. retries)Serverless/Dedicated/Self-Hosted
sql.ttl.changefeed_replication.disabled
booleanfalseif true, deletes issued by TTL will not be replicated via changefeedsServerless/Dedicated/Self-Hosted
sql.ttl.default_delete_batch_size
integer100default amount of rows to delete in a single query during a TTL jobServerless/Dedicated/Self-Hosted
sql.ttl.default_delete_rate_limit
integer100default delete rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Serverless/Dedicated/Self-Hosted
sql.ttl.default_select_batch_size
integer500default amount of rows to select in a single query during a TTL jobServerless/Dedicated/Self-Hosted
sql.ttl.default_select_rate_limit
integer0default select rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Serverless/Dedicated/Self-Hosted
sql.ttl.job.enabled
booleantruewhether the TTL job is enabledServerless/Dedicated/Self-Hosted
sql.txn.read_committed_isolation.enabled
booleanfalseset to true to allow transactions to use the READ COMMITTED isolation level if specified by BEGIN/SET commandsServerless/Dedicated/Self-Hosted
sql.txn_fingerprint_id_cache.capacity
integer100the maximum number of txn fingerprint IDs storedServerless/Dedicated/Self-Hosted
storage.experimental.eventually_file_only_snapshots.enabled
booleanfalseset to true to use eventually-file-only-snapshots even when kv.snapshot_receiver.excise.enabled is falseDedicated/Self-Hosted
storage.ingest_split.enabled
booleanfalseset to true to use ingest-time splitting to lower write-amplification (experimental)Dedicated/Self-Hosted
storage.max_sync_duration
duration20smaximum duration for disk operations; any operations that take longer than this setting trigger a warning log entry or process crashServerless/Dedicated/Self-Hosted (read-only)
storage.max_sync_duration.fatal.enabled
booleantrueif true, fatal the process when a disk operation exceeds storage.max_sync_durationServerless/Dedicated/Self-Hosted
storage.value_blocks.enabled
booleantrueset to true to enable writing of value blocks in sstablesServerless/Dedicated/Self-Hosted
timeseries.storage.enabled
booleantrueif set, periodic timeseries data is stored within the cluster; disabling is not recommended unless you are storing the data elsewhereDedicated/Self-Hosted
timeseries.storage.resolution_10s.ttl
duration240h0m0sthe maximum age of time series data stored at the 10 second resolution. Data older than this is subject to rollup and deletion.Serverless/Dedicated/Self-Hosted (read-only)
timeseries.storage.resolution_30m.ttl
duration2160h0m0sthe maximum age of time series data stored at the 30 minute resolution. Data older than this is subject to deletion.Serverless/Dedicated/Self-Hosted (read-only)
trace.debug_http_endpoint.enabled
(alias: trace.debug.enable)
booleanfalseif set, traces for recent requests can be seen at https://<ui>/debug/requestsServerless/Dedicated/Self-Hosted
trace.opentelemetry.collector
stringaddress of an OpenTelemetry trace collector to receive traces using the otel gRPC protocol, as <host>:<port>. If no port is specified, 4317 will be used.Serverless/Dedicated/Self-Hosted
trace.snapshot.rate
duration0sif non-zero, interval at which background trace snapshots are capturedServerless/Dedicated/Self-Hosted
trace.span_registry.enabled
booleantrueif set, ongoing traces can be seen at https://<ui>/#/debug/tracezServerless/Dedicated/Self-Hosted
trace.zipkin.collector
stringthe address of a Zipkin instance to receive traces, as <host>:<port>. If no port is specified, 9411 will be used.Serverless/Dedicated/Self-Hosted
ui.database_locality_metadata.enabled
booleantrueif enabled shows extended locality data about databases and tables in DB Console which can be expensive to computeServerless/Dedicated/Self-Hosted
ui.display_timezone
enumerationetc/utcthe timezone used to format timestamps in the ui [etc/utc = 0, america/new_york = 1]Serverless/Dedicated/Self-Hosted
version
version23.2set the active cluster version in the format '<major>.<minor>'Serverless/Dedicated/Self-Hosted
diff --git a/src/current/_includes/cockroach-generated/release-23.2/sql/aggregates.md b/src/current/_includes/cockroach-generated/release-23.2/sql/aggregates.md new file mode 100644 index 00000000000..fe8a7b0a0bb --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-23.2/sql/aggregates.md @@ -0,0 +1,531 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_agg(arg1: bool) → bool[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes) → bytes[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date) → date[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal) → decimal[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float) → float[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet) → inet[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int) → int[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval) → interval[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string) → string[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time) → time[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp) → timestamp[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz) → timestamptz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid) → uuid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum) → anyenum[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d) → box2d[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography) → geography[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry) → geometry[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb) → jsonb[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid) → oid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn) → pg_lsn[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor) → refcursor[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz) → timetz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple) → tuple[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit) → varbit[]

Aggregates the selected values into an array.

+		Immutable
array_cat_agg(arg1: bool[]) → bool[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: bytes[]) → bytes[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: date[]) → date[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: decimal[]) → decimal[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: float[]) → float[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: inet[]) → inet[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: int[]) → int[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: interval[]) → interval[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: string[]) → string[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: time[]) → time[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamp[]) → timestamp[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamptz[]) → timestamptz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: uuid[]) → uuid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: anyenum[]) → anyenum[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: box2d[]) → box2d[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geography[]) → geography[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geometry[]) → geometry[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: jsonb[]) → jsonb[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: oid[]) → oid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: pg_lsn[]) → pg_lsn[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: refcursor[]) → refcursor[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timetz[]) → timetz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: tuple[]) → tuple[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: varbit[]) → varbit[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
avg(arg1: decimal) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: float) → float

Calculates the average of the selected values.

+		Immutable
avg(arg1: int) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: interval) → interval

Calculates the average of the selected values.

+		Immutable
bit_and(arg1: int) → int

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_and(arg1: varbit) → varbit

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: int) → int

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: varbit) → varbit

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bool_and(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
bool_or(arg1: bool) → bool

Calculates the boolean value of ORing all selected values.

+		Immutable
concat_agg(arg1: bytes) → bytes

Concatenates all selected values.

+		Immutable
concat_agg(arg1: string) → string

Concatenates all selected values.

+		Immutable
corr(arg1: decimal, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
count(arg1: anyelement) → int

Calculates the number of selected elements.

+		Immutable
count_rows() → int

Calculates the number of rows.

+		Immutable
covar_pop(arg1: decimal, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
every(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
json_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
json_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
jsonb_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
jsonb_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
max(arg1: bool) → bool

Identifies the maximum selected value.

+		Immutable
max(arg1: bytes) → bytes

Identifies the maximum selected value.

+		Immutable
max(arg1: date) → date

Identifies the maximum selected value.

+		Immutable
max(arg1: decimal) → decimal

Identifies the maximum selected value.

+		Immutable
max(arg1: float) → float

Identifies the maximum selected value.

+		Immutable
max(arg1: inet) → inet

Identifies the maximum selected value.

+		Immutable
max(arg1: int) → int

Identifies the maximum selected value.

+		Immutable
max(arg1: interval) → interval

Identifies the maximum selected value.

+		Immutable
max(arg1: string) → string

Identifies the maximum selected value.

+		Immutable
max(arg1: time) → time

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamp) → timestamp

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamptz) → timestamptz

Identifies the maximum selected value.

+		Immutable
max(arg1: uuid) → uuid

Identifies the maximum selected value.

+		Immutable
max(arg1: anyenum) → anyenum

Identifies the maximum selected value.

+		Immutable
max(arg1: box2d) → box2d

Identifies the maximum selected value.

+		Immutable
max(arg1: collatedstring{*}) → collatedstring{*}

Identifies the maximum selected value.

+		Immutable
max(arg1: geography) → geography

Identifies the maximum selected value.

+		Immutable
max(arg1: geometry) → geometry

Identifies the maximum selected value.

+		Immutable
max(arg1: jsonb) → jsonb

Identifies the maximum selected value.

+		Immutable
max(arg1: oid) → oid

Identifies the maximum selected value.

+		Immutable
max(arg1: pg_lsn) → pg_lsn

Identifies the maximum selected value.

+		Immutable
max(arg1: timetz) → timetz

Identifies the maximum selected value.

+		Immutable
max(arg1: varbit) → varbit

Identifies the maximum selected value.

+		Immutable
min(arg1: bool) → bool

Identifies the minimum selected value.

+		Immutable
min(arg1: bytes) → bytes

Identifies the minimum selected value.

+		Immutable
min(arg1: date) → date

Identifies the minimum selected value.

+		Immutable
min(arg1: decimal) → decimal

Identifies the minimum selected value.

+		Immutable
min(arg1: float) → float

Identifies the minimum selected value.

+		Immutable
min(arg1: inet) → inet

Identifies the minimum selected value.

+		Immutable
min(arg1: int) → int

Identifies the minimum selected value.

+		Immutable
min(arg1: interval) → interval

Identifies the minimum selected value.

+		Immutable
min(arg1: string) → string

Identifies the minimum selected value.

+		Immutable
min(arg1: time) → time

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamp) → timestamp

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamptz) → timestamptz

Identifies the minimum selected value.

+		Immutable
min(arg1: uuid) → uuid

Identifies the minimum selected value.

+		Immutable
min(arg1: anyenum) → anyenum

Identifies the minimum selected value.

+		Immutable
min(arg1: box2d) → box2d

Identifies the minimum selected value.

+		Immutable
min(arg1: collatedstring{*}) → collatedstring{*}

Identifies the minimum selected value.

+		Immutable
min(arg1: geography) → geography

Identifies the minimum selected value.

+		Immutable
min(arg1: geometry) → geometry

Identifies the minimum selected value.

+		Immutable
min(arg1: jsonb) → jsonb

Identifies the minimum selected value.

+		Immutable
min(arg1: oid) → oid

Identifies the minimum selected value.

+		Immutable
min(arg1: pg_lsn) → pg_lsn

Identifies the minimum selected value.

+		Immutable
min(arg1: timetz) → timetz

Identifies the minimum selected value.

+		Immutable
min(arg1: varbit) → varbit

Identifies the minimum selected value.

+		Immutable
percentile_cont(arg1: float) → float

Continuous percentile: returns a float corresponding to the specified fraction in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float) → interval

Continuous percentile: returns an interval corresponding to the specified fraction in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_cont(arg1: float[]) → float[]

Continuous percentile: returns floats corresponding to the specified fractions in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float[]) → interval[]

Continuous percentile: returns intervals corresponding to the specified fractions in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_disc(arg1: float) → anyelement

Discrete percentile: returns the first input value whose position in the ordering equals or exceeds the specified fraction.

+		Immutable
percentile_disc(arg1: float[]) → anyelement

Discrete percentile: returns input values whose position in the ordering equals or exceeds the specified fractions.

+		Immutable
regr_avgx(arg1: decimal, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_count(arg1: decimal, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_intercept(arg1: decimal, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_r2(arg1: decimal, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_slope(arg1: decimal, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_sxx(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
sqrdiff(arg1: decimal) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: float) → float

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: int) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
st_collect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_extent(arg1: geometry) → box2d

Forms a Box2D that encapsulates all provided geometries.

+		Immutable
st_makeline(arg1: geometry) → geometry

Forms a LineString from Point, MultiPoint or LineStrings. Other shapes will be ignored.

+		Immutable
st_memcollect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_memunion(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
st_union(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
stddev(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: decimal) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: float) → float

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: int) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
string_agg(arg1: bytes, arg2: bytes) → bytes

Concatenates all selected values using the provided delimiter.

+		Immutable
string_agg(arg1: string, arg2: string) → string

Concatenates all selected values using the provided delimiter.

+		Immutable
sum(arg1: decimal) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: float) → float

Calculates the sum of the selected values.

+		Immutable
sum(arg1: int) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: interval) → interval

Calculates the sum of the selected values.

+		Immutable
sum_int(arg1: int) → int

Calculates the sum of the selected values.

+		Immutable
var_pop(arg1: decimal) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: float) → float

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: int) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_samp(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
variance(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
xor_agg(arg1: bytes) → bytes

Calculates the bitwise XOR of the selected values.

+		Immutable
xor_agg(arg1: int) → int

Calculates the bitwise XOR of the selected values.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-23.2/sql/functions.md b/src/current/_includes/cockroach-generated/release-23.2/sql/functions.md new file mode 100644 index 00000000000..370dfb4cfcd --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-23.2/sql/functions.md @@ -0,0 +1,3436 @@ +### Array functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_append(array: bool[], elem: bool) → bool[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: bytes[], elem: bytes) → bytes[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: date[], elem: date) → date[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: decimal[], elem: decimal) → decimal[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: float[], elem: float) → float[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: inet[], elem: inet) → inet[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: int[], elem: int) → int[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: interval[], elem: interval) → interval[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: string[], elem: string) → string[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: time[], elem: time) → time[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamp[], elem: timestamp) → timestamp[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamptz[], elem: timestamptz) → timestamptz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: uuid[], elem: uuid) → uuid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: anyenum[], elem: anyenum) → anyenum[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: box2d[], elem: box2d) → box2d[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geography[], elem: geography) → geography[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geometry[], elem: geometry) → geometry[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: jsonb[], elem: jsonb) → jsonb[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: oid[], elem: oid) → oid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: refcursor[], elem: refcursor) → refcursor[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timetz[], elem: timetz) → timetz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: tuple[], elem: tuple) → tuple[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: varbit[], elem: varbit) → varbit[]

Appends elem to array, returning the result.

+		Immutable
array_cat(left: bool[], right: bool[]) → bool[]

Appends two arrays.

+		Immutable
array_cat(left: bytes[], right: bytes[]) → bytes[]

Appends two arrays.

+		Immutable
array_cat(left: date[], right: date[]) → date[]

Appends two arrays.

+		Immutable
array_cat(left: decimal[], right: decimal[]) → decimal[]

Appends two arrays.

+		Immutable
array_cat(left: float[], right: float[]) → float[]

Appends two arrays.

+		Immutable
array_cat(left: inet[], right: inet[]) → inet[]

Appends two arrays.

+		Immutable
array_cat(left: int[], right: int[]) → int[]

Appends two arrays.

+		Immutable
array_cat(left: interval[], right: interval[]) → interval[]

Appends two arrays.

+		Immutable
array_cat(left: string[], right: string[]) → string[]

Appends two arrays.

+		Immutable
array_cat(left: time[], right: time[]) → time[]

Appends two arrays.

+		Immutable
array_cat(left: timestamp[], right: timestamp[]) → timestamp[]

Appends two arrays.

+		Immutable
array_cat(left: timestamptz[], right: timestamptz[]) → timestamptz[]

Appends two arrays.

+		Immutable
array_cat(left: uuid[], right: uuid[]) → uuid[]

Appends two arrays.

+		Immutable
array_cat(left: anyenum[], right: anyenum[]) → anyenum[]

Appends two arrays.

+		Immutable
array_cat(left: box2d[], right: box2d[]) → box2d[]

Appends two arrays.

+		Immutable
array_cat(left: geography[], right: geography[]) → geography[]

Appends two arrays.

+		Immutable
array_cat(left: geometry[], right: geometry[]) → geometry[]

Appends two arrays.

+		Immutable
array_cat(left: jsonb[], right: jsonb[]) → jsonb[]

Appends two arrays.

+		Immutable
array_cat(left: oid[], right: oid[]) → oid[]

Appends two arrays.

+		Immutable
array_cat(left: pg_lsn[], right: pg_lsn[]) → pg_lsn[]

Appends two arrays.

+		Immutable
array_cat(left: refcursor[], right: refcursor[]) → refcursor[]

Appends two arrays.

+		Immutable
array_cat(left: timetz[], right: timetz[]) → timetz[]

Appends two arrays.

+		Immutable
array_cat(left: tuple[], right: tuple[]) → tuple[]

Appends two arrays.

+		Immutable
array_cat(left: varbit[], right: varbit[]) → varbit[]

Appends two arrays.

+		Immutable
array_length(input: anyelement[], array_dimension: int) → int

Calculates the length of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_lower(input: anyelement[], array_dimension: int) → int

Calculates the minimum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_position(array: bool[], elem: bool) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bytes[], elem: bytes) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: date[], elem: date) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: decimal[], elem: decimal) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: float[], elem: float) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: inet[], elem: inet) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: int[], elem: int) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: interval[], elem: interval) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: string[], elem: string) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: time[], elem: time) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamp[], elem: timestamp) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: uuid[], elem: uuid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: anyenum[], elem: anyenum) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: box2d[], elem: box2d) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geography[], elem: geography) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geometry[], elem: geometry) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: jsonb[], elem: jsonb) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: oid[], elem: oid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: refcursor[], elem: refcursor) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timetz[], elem: timetz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: tuple[], elem: tuple) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: varbit[], elem: varbit) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_positions(array: bool[], elem: bool) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: bytes[], elem: bytes) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: date[], elem: date) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: decimal[], elem: decimal) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: float[], elem: float) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: inet[], elem: inet) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: int[], elem: int) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: interval[], elem: interval) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: string[], elem: string) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: time[], elem: time) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamp[], elem: timestamp) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamptz[], elem: timestamptz) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: uuid[], elem: uuid) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: anyenum[], elem: anyenum) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: box2d[], elem: box2d) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geography[], elem: geography) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geometry[], elem: geometry) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: jsonb[], elem: jsonb) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: oid[], elem: oid) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: pg_lsn[], elem: pg_lsn) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: refcursor[], elem: refcursor) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timetz[], elem: timetz) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: tuple[], elem: tuple) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: varbit[], elem: varbit) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_prepend(elem: bool, array: bool[]) → bool[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: bytes, array: bytes[]) → bytes[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: date, array: date[]) → date[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: decimal, array: decimal[]) → decimal[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: float, array: float[]) → float[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: inet, array: inet[]) → inet[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: int, array: int[]) → int[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: interval, array: interval[]) → interval[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: string, array: string[]) → string[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: time, array: time[]) → time[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamp, array: timestamp[]) → timestamp[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamptz, array: timestamptz[]) → timestamptz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: uuid, array: uuid[]) → uuid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: anyenum, array: anyenum[]) → anyenum[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: box2d, array: box2d[]) → box2d[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geography, array: geography[]) → geography[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geometry, array: geometry[]) → geometry[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: jsonb, array: jsonb[]) → jsonb[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: oid, array: oid[]) → oid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: pg_lsn, array: pg_lsn[]) → pg_lsn[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: refcursor, array: refcursor[]) → refcursor[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timetz, array: timetz[]) → timetz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: tuple, array: tuple[]) → tuple[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: varbit, array: varbit[]) → varbit[]

Prepends elem to array, returning the result.

+		Immutable
array_remove(array: bool[], elem: bool) → bool[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: bytes[], elem: bytes) → bytes[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: date[], elem: date) → date[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: decimal[], elem: decimal) → decimal[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: float[], elem: float) → float[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: inet[], elem: inet) → inet[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: int[], elem: int) → int[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: interval[], elem: interval) → interval[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: string[], elem: string) → string[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: time[], elem: time) → time[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamp[], elem: timestamp) → timestamp[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamptz[], elem: timestamptz) → timestamptz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: uuid[], elem: uuid) → uuid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: anyenum[], elem: anyenum) → anyenum[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: box2d[], elem: box2d) → box2d[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geography[], elem: geography) → geography[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geometry[], elem: geometry) → geometry[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: jsonb[], elem: jsonb) → jsonb[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: oid[], elem: oid) → oid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: refcursor[], elem: refcursor) → refcursor[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timetz[], elem: timetz) → timetz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: tuple[], elem: tuple) → tuple[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: varbit[], elem: varbit) → varbit[]

Remove from array all elements equal to elem.

+		Immutable
array_replace(array: bool[], toreplace: bool, replacewith: bool) → bool[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: bytes[], toreplace: bytes, replacewith: bytes) → bytes[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: date[], toreplace: date, replacewith: date) → date[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: decimal[], toreplace: decimal, replacewith: decimal) → decimal[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: float[], toreplace: float, replacewith: float) → float[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: inet[], toreplace: inet, replacewith: inet) → inet[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: int[], toreplace: int, replacewith: int) → int[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: interval[], toreplace: interval, replacewith: interval) → interval[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: string[], toreplace: string, replacewith: string) → string[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: time[], toreplace: time, replacewith: time) → time[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamp[], toreplace: timestamp, replacewith: timestamp) → timestamp[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamptz[], toreplace: timestamptz, replacewith: timestamptz) → timestamptz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: uuid[], toreplace: uuid, replacewith: uuid) → uuid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: anyenum[], toreplace: anyenum, replacewith: anyenum) → anyenum[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: box2d[], toreplace: box2d, replacewith: box2d) → box2d[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geography[], toreplace: geography, replacewith: geography) → geography[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geometry[], toreplace: geometry, replacewith: geometry) → geometry[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: jsonb[], toreplace: jsonb, replacewith: jsonb) → jsonb[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: oid[], toreplace: oid, replacewith: oid) → oid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: pg_lsn[], toreplace: pg_lsn, replacewith: pg_lsn) → pg_lsn[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: refcursor[], toreplace: refcursor, replacewith: refcursor) → refcursor[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timetz[], toreplace: timetz, replacewith: timetz) → timetz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: tuple[], toreplace: tuple, replacewith: tuple) → tuple[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: varbit[], toreplace: varbit, replacewith: varbit) → varbit[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_to_string(input: anyelement[], delim: string) → string

Join an array into a string with a delimiter.

+		Stable
array_to_string(input: anyelement[], delimiter: string, null: string) → string

Join an array into a string with a delimiter, replacing NULLs with a null string.

+		Stable
array_upper(input: anyelement[], array_dimension: int) → int

Calculates the maximum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
cardinality(input: anyelement[]) → int

Calculates the number of elements contained in input

+		Immutable
jsonb_array_to_string_array(input: jsonb) → string[]

Convert a JSONB array into a string array.

+		Immutable
string_to_array(str: string, delimiter: string) → string[]

Split a string into components on a delimiter.

+		Immutable
string_to_array(str: string, delimiter: string, null: string) → string[]

Split a string into components on a delimiter with a specified string to consider NULL.

+		Immutable
+ +### BOOL functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Matches case insensetively unescaped with pattern using escape as an escape token.

+		Immutable
inet_contained_by_or_equals(val: inet, container: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_contains_or_equals(container: inet, val: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_same_family(val: inet, val: inet) → bool

Checks if two IP addresses are of the same IP family.

+		Immutable
like_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
not_ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches case insensetively with pattern using escape as an escape token.

+		Immutable
not_like_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
not_similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
+ +### Comparison functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
greatest(anyelement...) → anyelement

Returns the element with the greatest value.

+		Immutable
least(anyelement...) → anyelement

Returns the element with the lowest value.

+		Immutable
num_nonnulls(anyelement...) → int

Returns the number of nonnull arguments.

+		Immutable
num_nulls(anyelement...) → int

Returns the number of null arguments.

+		Immutable
+ +### Cryptographic functions + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crypt(password: string, salt: string) → string

Generates a hash based on a password and salt. The hash algorithm and number of rounds if applicable are encoded in the salt.

+		Immutable
decrypt(data: bytes, key: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
decrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
digest(data: bytes, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
digest(data: string, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
encrypt(data: bytes, key: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
encrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
gen_random_bytes(count: int) → bytes

Returns count cryptographically strong random bytes. At most 1024 bytes can be extracted at a time.

+		Volatile
gen_salt(type: string) → string

Generates a salt for input into the crypt function using the default number of rounds.

+		Volatile
gen_salt(type: string, iter_count: int) → string

Generates a salt for input into the crypt function using iter_count number of rounds.

+		Volatile
hmac(data: bytes, key: bytes, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
hmac(data: string, key: string, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
+ +### DECIMAL functions + + + + + +
Function → ReturnsDescriptionVolatility
hlc_to_timestamp(hlc: decimal) → timestamptz

Returns a TimestampTZ representation of a CockroachDB HLC in decimal form.

+

Note that a TimestampTZ has less precision than a CockroachDB HLC. It is intended as +a convenience function to display HLCs in a print-friendly form. Use the decimal +value if you rely on the HLC for accuracy.

+		Immutable
+ +### Date and time functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
age(end: timestamptz, begin: timestamptz) → interval

Calculates the interval between begin and end, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use the timestamptz subtraction operator.

+		Immutable
age(val: timestamptz) → interval

Calculates the interval between val and the current time, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use now() - timestamptz.

+		Stable
clock_timestamp() → timestamp

Returns the current system time on one of the cluster nodes.

+		Volatile
clock_timestamp() → timestamptz

Returns the current system time on one of the cluster nodes.

+		Volatile
current_date() → date

Returns the date of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_timestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
date_part(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
date_part(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
date_trunc(element: string, input: date) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: interval) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: time) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero.

+

Compatible elements: hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamp) → timestamp

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamptz) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: timestamptz, timezone: string) → timestamptz

Truncates input to precision element in the specified timezone. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
experimental_follower_read_timestamp() → timestamptz

Same as follower_read_timestamp. This name is deprecated.

+		Volatile
experimental_strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
extract(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
extract(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
extract_duration(element: string, input: interval) → int

Extracts element from input. +Compatible elements: hour, minute, second, millisecond, microsecond. +This is deprecated in favor of extract which supports duration.

+		Immutable
follower_read_timestamp() → timestamptz

Returns a timestamp which is very likely to be safe to perform +against a follower replica.

+

This function is intended to be used with an AS OF SYSTEM TIME clause to perform +historical reads against a time which is recent but sufficiently old for reads +to be performed against the closest replica as opposed to the currently +leaseholder for a given range.

+

Note that this function requires an enterprise license on a CCL distribution to +return a result that is less likely the closest replica. It is otherwise +hardcoded as -4.8s from the statement time, which may not result in reading from the +nearest replica.

+		Volatile
localtimestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
make_date(year: int, month: int, day: int) → date

Create date (formatted according to ISO 8601) from year, month, and day fields (negative years signify BC).

+		Immutable
make_timestamp(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamp

Create timestamp (formatted according to ISO 8601) from year, month, day, hour, minute, and seconds fields (negative years signify BC).

+		Immutable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float, timezone: string) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
now() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
overlaps(s1: date, e1: date, s1: date, e2: date) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: date, e1: interval, s1: date, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: interval, s1: time, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: time, s1: time, e2: time) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: interval, s1: timestamp, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: timestamp, s1: timestamp, e2: timestamp) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamptz, e1: interval, s1: timestamptz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Stable
overlaps(s1: timestamptz, e1: timestamptz, s1: timestamptz, e2: timestamptz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: interval, s1: timetz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: timetz, s1: timetz, e2: timetz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
statement_timestamp() → timestamp

Returns the start time of the current statement.

+		Stable
statement_timestamp() → timestamptz

Returns the start time of the current statement.

+		Stable
strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
timeofday() → string

Returns the current system time on one of the cluster nodes as a string.

+		Stable
timezone(timezone: string, time: time) → timetz

Treat given time without time zone as located in the specified time zone.

+		Stable
timezone(timezone: string, timestamp: timestamp) → timestamptz

Treat given time stamp without time zone as located in the specified time zone.

+		Immutable
timezone(timezone: string, timestamptz: timestamptz) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Immutable
timezone(timezone: string, timestamptz_string: string) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Stable
timezone(timezone: string, timetz: timetz) → timetz

Convert given time with time zone to the new time zone.

+		Stable
to_char(date: date) → string

Convert an date to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(date: date, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_char(interval: interval) → string

Convert an interval to a string assuming the Postgres IntervalStyle.

+		Immutable
to_char(interval: interval, format: string) → string

Convert an interval to a string using the given format.

+		Stable
to_char(timestamp: timestamp) → string

Convert an timestamp to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(timestamp: timestamp, format: string) → string

Convert an timestamp to a string using the given format.

+		Stable
to_char(timestamptz: timestamptz, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_timestamp(timestamp: float) → timestamptz

Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to timestamp with time zone.

+		Immutable
transaction_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
with_max_staleness(max_staleness: interval) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_max_staleness(max_staleness: interval, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
+ +### Enum functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
enum_first(val: anyenum) → anyenum

Returns the first value of the input enum type.

+		Stable
enum_last(val: anyenum) → anyenum

Returns the last value of the input enum type.

+		Stable
enum_range(lower: anyenum, upper: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array between the two arguments (inclusive).

+		Stable
enum_range(val: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array.

+		Stable
+ +### FLOAT functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abs(val: decimal) → decimal

Calculates the absolute value of val.

+		Immutable
abs(val: float) → float

Calculates the absolute value of val.

+		Immutable
abs(val: int) → int

Calculates the absolute value of val.

+		Immutable
acos(val: float) → float

Calculates the inverse cosine of val.

+		Immutable
acosd(val: float) → float

Calculates the inverse cosine of val with the result in degrees

+		Immutable
acosh(val: float) → float

Calculates the inverse hyperbolic cosine of val.

+		Immutable
asin(val: float) → float

Calculates the inverse sine of val.

+		Immutable
asind(val: float) → float

Calculates the inverse sine of val with the result in degrees.

+		Immutable
asinh(val: float) → float

Calculates the inverse hyperbolic sine of val.

+		Immutable
atan(val: float) → float

Calculates the inverse tangent of val.

+		Immutable
atan2(x: float, y: float) → float

Calculates the inverse tangent of x/y.

+		Immutable
atan2d(x: float, y: float) → float

Calculates the inverse tangent of x/y with the result in degrees

+		Immutable
atand(val: float) → float

Calculates the inverse tangent of val with the result in degrees.

+		Immutable
atanh(val: float) → float

Calculates the inverse hyperbolic tangent of val.

+		Immutable
cbrt(val: decimal) → decimal

Calculates the cube root (∛) of val.

+		Immutable
cbrt(val: float) → float

Calculates the cube root (∛) of val.

+		Immutable
ceil(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
cos(val: float) → float

Calculates the cosine of val.

+		Immutable
cosd(val: float) → float

Calculates the cosine of val where val is in degrees.

+		Immutable
cosh(val: float) → float

Calculates the hyperbolic cosine of val.

+		Immutable
cot(val: float) → float

Calculates the cotangent of val.

+		Immutable
cotd(val: float) → float

Calculates the cotangent of val where val is in degrees.

+		Immutable
degrees(val: float) → float

Converts val as a radian value to a degree value.

+		Immutable
div(x: decimal, y: decimal) → decimal

Calculates the integer quotient of x/y.

+		Immutable
div(x: float, y: float) → float

Calculates the integer quotient of x/y.

+		Immutable
div(x: int, y: int) → int

Calculates the integer quotient of x/y.

+		Immutable
exp(val: decimal) → decimal

Calculates e ^ val.

+		Immutable
exp(val: float) → float

Calculates e ^ val.

+		Immutable
floor(val: decimal) → decimal

Calculates the largest integer not greater than val.

+		Immutable
floor(val: float) → float

Calculates the largest integer not greater than val.

+		Immutable
floor(val: int) → float

Calculates the largest integer not greater than val.

+		Immutable
isnan(val: decimal) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
isnan(val: float) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
ln(val: decimal) → decimal

Calculates the natural log of val.

+		Immutable
ln(val: float) → float

Calculates the natural log of val.

+		Immutable
log(b: decimal, x: decimal) → decimal

Calculates the base b log of val.

+		Immutable
log(b: float, x: float) → float

Calculates the base b log of val.

+		Immutable
log(val: decimal) → decimal

Calculates the base 10 log of val.

+		Immutable
log(val: float) → float

Calculates the base 10 log of val.

+		Immutable
mod(x: decimal, y: decimal) → decimal

Calculates x%y.

+		Immutable
mod(x: float, y: float) → float

Calculates x%y.

+		Immutable
mod(x: int, y: int) → int

Calculates x%y.

+		Immutable
pi() → float

Returns the value for pi (3.141592653589793).

+		Immutable
pow(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
pow(x: float, y: float) → float

Calculates x^y.

+		Immutable
pow(x: int, y: int) → int

Calculates x^y.

+		Immutable
power(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
power(x: float, y: float) → float

Calculates x^y.

+		Immutable
power(x: int, y: int) → int

Calculates x^y.

+		Immutable
radians(val: float) → float

Converts val as a degree value to a radians value.

+		Immutable
random() → float

Returns a random floating-point number between 0 (inclusive) and 1 (exclusive). Note that the value contains at most 53 bits of randomness.

+		Volatile
round(input: decimal, decimal_accuracy: int) → decimal

Keeps decimal_accuracy number of figures to the right of the zero position in input using half away from zero rounding. If decimal_accuracy is not in the range -2^31…(2^31-1), the results are undefined.

+		Immutable
round(input: float, decimal_accuracy: int) → float

Keeps decimal_accuracy number of figures to the right of the zero position in input using half to even (banker’s) rounding.

+		Immutable
round(val: decimal) → decimal

Rounds val to the nearest integer, half away from zero: round(+/-2.4) = +/-2, round(+/-2.5) = +/-3.

+		Immutable
round(val: float) → float

Rounds val to the nearest integer using half to even (banker’s) rounding.

+		Immutable
sign(val: decimal) → decimal

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: float) → float

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: int) → int

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sin(val: float) → float

Calculates the sine of val.

+		Immutable
sind(val: float) → float

Calculates the sine of val where val is in degrees.

+		Immutable
sinh(val: float) → float

Calculates the hyperbolic sine of val.

+		Immutable
sqrt(val: decimal) → decimal

Calculates the square root of val.

+		Immutable
sqrt(val: float) → float

Calculates the square root of val.

+		Immutable
tan(val: float) → float

Calculates the tangent of val.

+		Immutable
tand(val: float) → float

Calculates the tangent of val where val is in degrees.

+		Immutable
tanh(val: float) → float

Calculates the hyperbolic tangent of val.

+		Immutable
trunc(val: decimal) → decimal

Truncates the decimal values of val.

+		Immutable
trunc(val: decimal, scale: int) → decimal

Truncate val to scale decimal places

+		Immutable
trunc(val: float) → float

Truncates the decimal values of val.

+		Immutable
+ +### Full Text Search functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
phraseto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The <-> operator is inserted between each token in the input.

+		Immutable
phraseto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The <-> operator is inserted between each token in the input.

+		Stable
plainto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The & operator is inserted between each token in the input.

+		Immutable
plainto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The & operator is inserted between each token in the input.

+		Stable
to_tsquery(config: string, text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the specified configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Immutable
to_tsquery(text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the default configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Stable
to_tsvector(config: string, text: string) → tsvector

Converts text to a tsvector, normalizing words according to the specified configuration. Position information is included in the result.

+		Immutable
to_tsvector(text: string) → tsvector

Converts text to a tsvector, normalizing words according to the default configuration. Position information is included in the result.

+		Stable
ts_parse(parser_name: string, document: string) → tuple{int AS tokid, string AS token}

ts_parse parses the given document and returns a series of records, one for each token produced by parsing. Each record includes a tokid showing the assigned token type and a token which is the text of the token.

+		Stable
ts_rank(vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
+ +### Fuzzy String Matching functions + + + + + + + +
Function → ReturnsDescriptionVolatility
levenshtein(source: string, target: string) → int

Calculates the Levenshtein distance between two strings. Maximum input length is 255 characters.

+		Immutable
levenshtein(source: string, target: string, ins_cost: int, del_cost: int, sub_cost: int) → int

Calculates the Levenshtein distance between two strings. The cost parameters specify how much to charge for each edit operation. Maximum input length is 255 characters.

+		Immutable
soundex(source: string) → string

Convert a string to its Soundex code.

+		Immutable
+ +### ID generation functions + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
experimental_uuid_v4() → bytes

Returns a UUID.

+		Volatile
gen_random_ulid() → uuid

Generates a random ULID and returns it as a value of UUID type.

+		Volatile
gen_random_uuid() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
unique_rowid() → int

Returns a unique ID used by CockroachDB to generate unique row IDs if a Primary Key isn’t defined for the table. The value is a combination of the insert timestamp and the ID of the node executing the statement, which guarantees this combination is globally unique. However, there can be gaps and the order is not completely guaranteed.

+		Volatile
unordered_unique_rowid() → int

Returns a unique ID. The value is a combination of the insert timestamp (bit-reversed) and the ID of the node executing the statement, which guarantees this combination is globally unique. The way it is generated is statistically likely to not have any ordering relative to previously generated values.

+		Volatile
uuid_generate_v1() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. To avoid exposing the server’s real MAC address, this uses a random MAC address and a timestamp. Essentially, this is an alias for uuid_generate_v1mc.

+		Volatile
uuid_generate_v1mc() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. This uses a random MAC address and a timestamp.

+		Volatile
uuid_generate_v3(namespace: uuid, name: string) → uuid

Generates a version 3 UUID in the given namespace using the specified input name, with md5 as the hashing method. The namespace should be one of the special constants produced by the uuid_ns_*() functions.

+		Immutable
uuid_generate_v4() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
uuid_generate_v5(namespace: uuid, name: string) → uuid

Generates a version 5 UUID in the given namespace using the specified input name. This is similar to a version 3 UUID, except it uses SHA-1 for hashing.

+		Immutable
uuid_nil() → uuid

Returns a nil UUID constant.

+		Immutable
uuid_ns_dns() → uuid

Returns a constant designating the DNS namespace for UUIDs.

+		Immutable
uuid_ns_oid() → uuid

Returns a constant designating the ISO object identifier (OID) namespace for UUIDs. These are unrelated to the OID type used internally in the database.

+		Immutable
uuid_ns_url() → uuid

Returns a constant designating the URL namespace for UUIDs.

+		Immutable
uuid_ns_x500() → uuid

Returns a constant designating the X.500 distinguished name (DN) namespace for UUIDs.

+		Immutable
uuid_v4() → bytes

Returns a UUID.

+		Volatile
+ +### INET functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abbrev(val: inet) → string

Converts the combined IP address and prefix length to an abbreviated display format as text.For INET types, this will omit the prefix length if it’s not the default (32 or IPv4, 128 for IPv6)

+

For example, abbrev('192.168.1.2/24') returns '192.168.1.2/24'

+		Immutable
broadcast(val: inet) → inet

Gets the broadcast address for the network address represented by the value.

+

For example, broadcast('192.168.1.2/24') returns '192.168.1.255/24'

+		Immutable
family(val: inet) → int

Extracts the IP family of the value; 4 for IPv4, 6 for IPv6.

+

For example, family('::1') returns 6

+		Immutable
host(val: inet) → string

Extracts the address part of the combined address/prefixlen value as text.

+

For example, host('192.168.1.2/16') returns '192.168.1.2'

+		Immutable
hostmask(val: inet) → inet

Creates an IP host mask corresponding to the prefix length in the value.

+

For example, hostmask('192.168.1.2/16') returns '0.0.255.255'

+		Immutable
masklen(val: inet) → int

Retrieves the prefix length stored in the value.

+

For example, masklen('192.168.1.2/16') returns 16

+		Immutable
netmask(val: inet) → inet

Creates an IP network mask corresponding to the prefix length in the value.

+

For example, netmask('192.168.1.2/16') returns '255.255.0.0'

+		Immutable
set_masklen(val: inet, prefixlen: int) → inet

Sets the prefix length of val to prefixlen.

+

For example, set_masklen('192.168.1.2', 16) returns '192.168.1.2/16'.

+		Immutable
+ +### INT functions + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crc32c(bytes...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32c(string...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32ieee(bytes...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
crc32ieee(string...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
fnv32(bytes...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32(string...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32a(bytes...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv32a(string...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64(bytes...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64(string...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64a(bytes...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64a(string...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
width_bucket(operand: decimal, b1: decimal, b2: decimal, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2.

+		Immutable
width_bucket(operand: int, b1: int, b2: int, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2.

+		Immutable
width_bucket(operand: anyelement, thresholds: anyelement[]) → int

return the bucket number to which operand would be assigned given an array listing the lower bounds of the buckets; returns 0 for an input less than the first lower bound; the thresholds array must be sorted, smallest first, or unexpected results will be obtained

+		Immutable
+ +### JSONB functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_to_json(array: anyelement[]) → jsonb

Returns the array as JSON or JSONB.

+		Stable
array_to_json(array: anyelement[], pretty_bool: bool) → jsonb

Returns the array as JSON or JSONB.

+		Stable
json_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
json_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
json_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
json_build_array(anyelement...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
json_build_object(anyelement...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
json_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
json_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
json_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
json_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
json_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
json_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
json_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
json_remove_path(val: jsonb, path: string[]) → jsonb

Remove the specified path from the JSON object.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
json_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
json_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
json_valid(string: string) → bool

Returns whether the given string is a valid JSON or not

+		Immutable
jsonb_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
jsonb_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
jsonb_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
jsonb_build_array(anyelement...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
jsonb_build_object(anyelement...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
jsonb_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
jsonb_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
jsonb_exists_any(json: jsonb, array: string[]) → bool

Returns whether any of the strings in the text array exist as top-level keys or array elements

+		Immutable
jsonb_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments. new_val will be inserted before path target.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb, insert_after: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If insert_after is true (default is false), new_val will be inserted after path target.

+		Immutable
jsonb_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
jsonb_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
jsonb_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
jsonb_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
jsonb_pretty(val: jsonb) → string

Returns the given JSON value as a STRING indented and with newlines.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
jsonb_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
jsonb_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
row_to_json(row: tuple) → jsonb

Returns the row as a JSON object.

+		Stable
to_json(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
to_jsonb(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
+ +### Multi-region functions + + + + + + + +
Function → ReturnsDescriptionVolatility
default_to_database_primary_region(val: string) → string

Returns the given region if the region has been added to the current database. +Otherwise, this will return the primary region of the current database. +This will error if the current database is not a multi-region database.

+		Stable
gateway_region() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
rehome_row() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
+ +### STRING[] functions + + + + + + +
Function → ReturnsDescriptionVolatility
regexp_split_to_array(string: string, pattern: string) → string[]

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_array(string: string, pattern: string, flags: string) → string[]

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
+ +### Sequence functions + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
currval(sequence_name: string) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
currval(sequence_name: regclass) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
lastval() → int

Return value most recently obtained with nextval in this session.

+		Volatile
nextval(sequence_name: string) → int

Advances the given sequence and returns its new value.

+		Volatile
nextval(sequence_name: regclass) → int

Advances the given sequence and returns its new value.

+		Volatile
setval(sequence_name: string, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: string, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
setval(sequence_name: regclass, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: regclass, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
+ +### Set-returning functions + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
aclexplode(aclitems: string[]) → tuple{oid AS grantor, oid AS grantee, string AS privilege_type, bool AS is_grantable}

Produces a virtual table containing aclitem stuff (returns no rows as this feature is unsupported in CockroachDB)

+		Stable
generate_series(start: int, end: int) → int

Produces a virtual table containing the integer values from start to end, inclusive.

+		Immutable
generate_series(start: int, end: int, step: int) → int

Produces a virtual table containing the integer values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamp, end: timestamp, step: interval) → timestamp

Produces a virtual table containing the timestamp values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamptz, end: timestamptz, step: interval) → timestamptz

Produces a virtual table containing the timestampTZ values from start to end, inclusive, by increment of step.

+		Immutable
generate_subscripts(array: anyelement[]) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int, reverse: bool) → int

Returns a series comprising the given array’s subscripts.

+

When reverse is true, the series is returned in reverse order.

+		Immutable
information_schema._pg_expandarray(input: anyelement[]) → tuple{anyelement AS x, int AS n}

Returns the input array as a set of rows with an index

+		Immutable
json_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
json_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
json_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
jsonb_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
jsonb_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
jsonb_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
pg_get_keywords() → tuple{string AS word, string AS catcode, string AS catdesc}

Produces a virtual table containing the keywords known to the SQL parser.

+		Immutable
pg_options_to_table(options: string[]) → tuple{string AS option_name, string AS option_value}

Converts the options array format to a table.

+		Stable
regexp_split_to_table(string: string, pattern: string) → string

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_table(string: string, pattern: string, flags: string) → string

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
unnest(anyelement[], anyelement[], anyelement[]...) → tuple{anyelement AS unnest, anyelement AS unnest, anyelement AS unnest}

Returns the input arrays as a set of rows

+		Immutable
unnest(input: anyelement[]) → anyelement

Returns the input array as a set of rows

+		Immutable
workload_index_recs() → string

Returns set of index recommendations

+		Immutable
workload_index_recs(timestamptz: timestamptz) → string

Returns set of index recommendations

+		Immutable
+ +### Spatial functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
_st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
geometrytype(geometry: geometry) → string

Returns the type of geometry as a string.

+

This function utilizes the GEOS module.

+		Immutable
geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
postgis_addbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_dropbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_extensions_upgrade() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_full_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_geos_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_getbbox(geometry: geometry) → box2d

Returns a box2d encapsulating the given Geometry.

+		Immutable
postgis_hasbbox(geometry: geometry) → bool

Returns whether a given Geometry has a bounding box. False for points and empty geometries; always true otherwise.

+		Immutable
postgis_lib_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_lib_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_liblwgeom_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_libxml_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_proj_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_installed() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_released() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_wagyu_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
st_addmeasure(geometry: geometry, start: float, end: float) → geometry

Returns a copy of a LineString or MultiLineString with measure coordinates linearly interpolated between the specified start and end values. Any existing M coordinates will be overwritten.

+		Immutable
st_addpoint(line_string: geometry, point: geometry) → geometry

Adds a Point to the end of a LineString.

+		Immutable
st_addpoint(line_string: geometry, point: geometry, index: int) → geometry

Adds a Point to a LineString at the given 0-based index (-1 to append).

+		Immutable
st_affine(geometry: geometry, a: float, b: float, c: float, d: float, e: float, f: float, g: float, h: float, i: float, x_off: float, y_off: float, z_off: float) → geometry

Applies a 3D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b c x_off \ / x
+| d e f y_off | | y | +| g h i z_off | | z | +\ 0 0 0 1 / \ 0 /

+		Immutable
st_affine(geometry: geometry, a: float, b: float, d: float, e: float, x_off: float, y_off: float) → geometry

Applies a 2D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b x_off \ / x
+| d e y_off | | y | +\ 0 0 1 / \ 0 /

+		Immutable
st_angle(line1: geometry, line2: geometry) → float

Returns the clockwise angle between two LINESTRING geometries, treating them as vectors between their start- and endpoints. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry) → float

Returns the clockwise angle between the vectors formed by point2,point1 and point2,point3. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry, point4: geometry) → float

Returns the clockwise angle between the vectors formed by point1,point2 and point3,point4. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_area(geography: geography) → float

Returns the area of the given geography in meters^2. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geography: geography, use_spheroid: bool) → float

Returns the area of the given geography in meters^2.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_area(geometry_str: string) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_area2d(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_asbinary(geography: geography) → bytes

Returns the WKB representation of a given Geography.

+		Immutable
st_asbinary(geography: geography, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asbinary(geometry: geometry) → bytes

Returns the WKB representation of a given Geometry.

+		Immutable
st_asbinary(geometry: geometry, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asencodedpolyline(geometry: geometry) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Preserves 5 decimal places.

+		Immutable
st_asencodedpolyline(geometry: geometry, precision: int4) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+		Immutable
st_asewkb(geography: geography) → bytes

Returns the EWKB representation of a given Geography.

+		Immutable
st_asewkb(geometry: geometry) → bytes

Returns the EWKB representation of a given Geometry.

+		Immutable
st_asewkt(geography: geography) → string

Returns the EWKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_asewkt(geography: geography, max_decimal_digits: int) → string

Returns the EWKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry: geometry) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_asewkt(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry_str: string) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asewkt(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geography: geography) → string

Returns the GeoJSON representation of a given Geography. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option (default for Geography)
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326
    • +
+		Immutable
st_asgeojson(geometry: geometry) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+		Immutable
st_asgeojson(geometry_str: string) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(row: tuple) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(row: tuple, geo_column: string) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. Coordinates have a maximum of 9 decimal digits.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int, pretty: bool) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value. Output will be pretty printed in JSON if pretty is true.

+		Stable
st_ashexewkb(geography: geography) → string

Returns the EWKB representation in hex of a given Geography.

+		Immutable
st_ashexewkb(geography: geography, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexewkb(geometry: geometry) → string

Returns the EWKB representation in hex of a given Geometry.

+		Immutable
st_ashexewkb(geometry: geometry, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexwkb(geography: geography) → string

Returns the WKB representation in hex of a given Geography.

+		Immutable
st_ashexwkb(geometry: geometry) → string

Returns the WKB representation in hex of a given Geometry.

+		Immutable
st_askml(geography: geography) → string

Returns the KML representation of a given Geography.

+		Immutable
st_askml(geometry: geometry) → string

Returns the KML representation of a given Geometry.

+		Immutable
st_askml(geometry_str: string) → string

Returns the KML representation of a given Geometry.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping. +Uses 4096 as the tile extent size in tile coordinate space.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int, clip: bool) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds if required.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry can be transformed, and clipped if required.

+		Immutable
st_astext(geography: geography) → string

Returns the WKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_astext(geography: geography, max_decimal_digits: int) → string

Returns the WKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry: geometry) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_astext(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry_str: string) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astext(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int, precision_m: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_azimuth(geography_a: geography, geography_b: geography) → float

Returns the azimuth in radians of the segment defined by the given point geographies, or NULL if the two points are coincident. It is solved using the Inverse geodesic problem.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_azimuth(geometry_a: geometry, geometry_b: geometry) → float

Returns the azimuth in radians of the segment defined by the given point geometries, or NULL if the two points are coincident.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+		Immutable
st_bdpolyfromtext(str: string, srid: int) → geometry

Returns a Polygon from multilinestring WKT with a SRID. If the input is not a multilinestring an error will be thrown.

+		Immutable
st_boundary(geometry: geometry) → geometry

Returns the closure of the combinatorial boundary of this Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_box2dfromgeohash(geohash: string) → box2d

Return a Box2D from a GeoHash string with max precision.

+		Immutable
st_box2dfromgeohash(geohash: string, precision: int) → box2d

Return a Box2D from a GeoHash string with supplied precision.

+		Immutable
st_buffer(geography: geography, distance: float) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, buffer_style_params: string) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, quad_segs: int) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geometry: geometry, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry_str: string, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_centroid(geography: geography) → geography

Returns the centroid of given geography. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geography: geography, use_spheroid: bool) → geography

Returns the centroid of given geography.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geometry: geometry) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_centroid(geometry_str: string) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_clipbybox2d(geometry: geometry, box2d: box2d) → geometry

Clips the geometry to conform to the bounding box specified by box2d.

+		Immutable
st_closestpoint(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the 2-dimensional point on geometry_a that is closest to geometry_b. This is the first point of the shortest line.

+		Immutable
st_collectionextract(geometry: geometry, type: int) → geometry

Given a collection, returns a multitype consisting only of elements of the specified type. If there are no elements of the given type, an EMPTY geometry is returned. Types are specified as 1=POINT, 2=LINESTRING, 3=POLYGON - other types are not supported.

+		Immutable
st_collectionhomogenize(geometry: geometry) → geometry

Returns the “simplest” representation of a collection’s contents. Collections of a single type will be returned as an appopriate multitype, or a singleton if it only contains a single geometry.

+		Immutable
st_combinebbox(box2d: box2d, geometry: geometry) → box2d

Combines the current bounding box with the bounding box of the Geometry.

+		Immutable
st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_convexhull(geometry: geometry) → geometry

Returns a geometry that represents the Convex Hull of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_coorddim(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_difference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the difference of two Geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_dimension(geometry: geometry) → int

Returns the number of topological dimensions of a given Geometry.

+		Immutable
st_disjoint(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a does not overlap, touch or is within geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_distance(geography_a: geography, geography_b: geography) → float

Returns the distance in meters between geography_a and geography_b. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geography_a: geography, geography_b: geography, use_spheroid: bool) → float

Returns the distance in meters between geography_a and geography_b.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance between the given geometries.

+		Immutable
st_distance(geometry_a_str: string, geometry_b_str: string) → float

Returns the distance between the given geometries.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_distancesphere(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_distancespheroid(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a spheroid.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_endpoint(geometry: geometry) → geometry

Returns the last point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_envelope(box2d: box2d) → geometry

Returns a bounding geometry for the given box.

+		Immutable
st_envelope(geometry: geometry) → geometry

Returns a bounding envelope for the given geometry.

+

For geometries which have a POINT or LINESTRING bounding box (i.e. is a single point +or a horizontal or vertical line), a POINT or LINESTRING is returned. Otherwise, the +returned POLYGON will be ordered Bottom Left, Top Left, Top Right, Bottom Right, +Bottom Left.

+		Immutable
st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string, parent_only: bool) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+

The parent_only boolean is always ignored.

+		Stable
st_estimatedextent(table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_expand(box2d: box2d, delta: float) → box2d

Extends the box2d by delta units across all dimensions.

+		Immutable
st_expand(box2d: box2d, delta_x: float, delta_y: float) → box2d

Extends the box2d by delta_x units in the x dimension and delta_y units in the y dimension.

+		Immutable
st_expand(geometry: geometry, delta: float) → geometry

Extends the bounding box represented by the geometry by delta units across all dimensions, returning a Polygon representing the new bounding box.

+		Immutable
st_expand(geometry: geometry, delta_x: float, delta_y: float) → geometry

Extends the bounding box represented by the geometry by delta_x units in the x dimension and delta_y units in the y dimension, returning a Polygon representing the new bounding box.

+		Immutable
st_exteriorring(geometry: geometry) → geometry

Returns the exterior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon.

+		Immutable
st_flipcoordinates(geometry: geometry) → geometry

Returns a new geometry with the X and Y axes flipped.

+		Immutable
st_force2d(geometry: geometry) → geometry

Returns a Geometry that is forced into XY layout with any Z or M dimensions discarded.

+		Immutable
st_force3d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to 0. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry, defaultM: float) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to the specified default M value. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force4d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZM layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float, defaultM: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified Z value. If a M coordinate doesn’t exist, it will be set to the specified M value.

+		Immutable
st_forcecollection(geometry: geometry) → geometry

Converts the geometry into a GeometryCollection.

+		Immutable
st_forcepolygonccw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_forcepolygoncw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Frechet distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Frechet distance between the given geometries, with the given segment densification (range 0.0-1.0, -1 to disable).

+

Smaller densify_frac gives a more accurate Fréchet distance. However, the computation time and memory usage increases with the square of the number of subsegments.

+

This function utilizes the GEOS module.

+		Immutable
st_generatepoints(geometry: geometry, npoints: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. Uses system time as a seed. +The requested number of points must be not larger than 65336.

+		Volatile
st_generatepoints(geometry: geometry, npoints: int4, seed: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. +The requested number of points must be not larger than 65336.

+		Immutable
st_geogfromewkb(val: bytes) → geography

Returns the Geography from an EWKB representation.

+		Immutable
st_geogfromewkt(val: string) → geography

Returns the Geography from an EWKT representation.

+		Immutable
st_geogfromgeojson(val: string) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromgeojson(val: jsonb) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geogfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geogfromwkb(bytes: bytes, srid: int) → geography

Returns the Geography from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geogfromwkb(val: bytes) → geography

Returns the Geography from a WKB (or EWKB) representation.

+		Immutable
st_geographyfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geographyfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geohash(geography: geography) → string

Returns a GeoHash representation of the geeographywith full precision if a point is provided, or with variable precision based on the size of the feature.

+		Immutable
st_geohash(geography: geography, precision: int) → string

Returns a GeoHash representation of the geography with the supplied precision.

+		Immutable
st_geohash(geometry: geometry) → string

Returns a GeoHash representation of the geometry with full precision if a point is provided, or with variable precision based on the size of the feature. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geohash(geometry: geometry, precision: int) → string

Returns a GeoHash representation of the geometry with the supplied precision. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geomcollfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomcollfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geometryfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geometryfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geometryn(geometry: geometry, n: int) → geometry

Returns the n-th Geometry (1-indexed). Returns NULL if out of bounds.

+		Immutable
st_geometrytype(geometry: geometry) → string

Returns the type of geometry as a string prefixed with ST_.

+

This function utilizes the GEOS module.

+		Immutable
st_geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
st_geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
st_geomfromgeohash(geohash: string) → geometry

Return a POLYGON Geometry from a GeoHash string with max precision.

+		Immutable
st_geomfromgeohash(geohash: string, precision: int) → geometry

Return a POLYGON Geometry from a GeoHash string with supplied precision.

+		Immutable
st_geomfromgeojson(val: string) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromgeojson(val: jsonb) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geomfromwkb(bytes: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geomfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_hasarc(geometry: geometry) → bool

Returns whether there is a CIRCULARSTRING in the geometry.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Hausdorff distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Hausdorff distance between the given geometries, with the given segment densification (range 0.0-1.0).

+

This function utilizes the GEOS module.

+		Immutable
st_interiorringn(geometry: geometry, n: int) → geometry

Returns the n-th (1-indexed) interior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon, or the ring does not exist.

+		Immutable
st_intersection(geography_a: geography, geography_b: geography) → geography

Returns the point intersections of the given geographies.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a_str: string, geometry_b_str: string) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_isclosed(geometry: geometry) → bool

Returns whether the geometry is closed as defined by whether the start and end points are coincident. Points are considered closed, empty geometries are not. For collections and multi-types, all members must be closed, as must all polygon rings.

+		Immutable
st_iscollection(geometry: geometry) → bool

Returns whether the geometry is of a collection type (including multi-types).

+		Immutable
st_isempty(geometry: geometry) → bool

Returns whether the geometry is empty.

+		Immutable
st_ispolygonccw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are considered counter-clockwise.

+		Immutable
st_ispolygoncw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are considered clockwise.

+		Immutable
st_isring(geometry: geometry) → bool

Returns whether the geometry is a single linestring that is closed and simple, as defined by ST_IsClosed and ST_IsSimple.

+

This function utilizes the GEOS module.

+		Immutable
st_issimple(geometry: geometry) → bool

Returns true if the geometry has no anomalous geometric points, e.g. that it intersects with or lies tangent to itself.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry) → bool

Returns whether the geometry is valid as defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry, flags: int) → bool

Returns whether the geometry is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry) → string

Returns a string containing the reason the geometry is invalid along with the point of interest, or “Valid Geometry” if it is valid. Validity is defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry, flags: int) → string

Returns the reason the geometry is invalid or “Valid Geometry” if it is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidtrajectory(geometry: geometry) → bool

Returns whether the geometry encodes a valid trajectory.

+

Note the geometry must be a LineString with M coordinates.

+		Immutable
st_length(geography: geography) → float

Returns the length of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geography: geography, use_spheroid: bool) → float

Returns the length of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_length(geometry_str: string) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_length2d(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_linecrossingdirection(linestring_a: geometry, linestring_b: geometry) → int

Returns an interger value defining behavior of crossing of lines: +0: lines do not cross, +-1: linestring_b crosses linestring_a from right to left, +1: linestring_b crosses linestring_a from left to right, +-2: linestring_b crosses linestring_a multiple times from right to left, +2: linestring_b crosses linestring_a multiple times from left to right, +-3: linestring_b crosses linestring_a multiple times from left to left, +3: linestring_b crosses linestring_a multiple times from right to right.

+

Note that the top vertex of the segment touching another line does not count as a crossing, but the bottom vertex of segment touching another line is considered a crossing.

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string) → geometry

Creates a LineString from an Encoded Polyline string.

+

Returns valid results only if the polyline was encoded with 5 decimal places.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string, precision: int4) → geometry

Creates a LineString from an Encoded Polyline string.

+

Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefrommultipoint(geometry: geometry) → geometry

Creates a LineString from a MultiPoint geometry.

+		Immutable
st_linefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_lineinterpolatepoint(geometry: geometry, fraction: float) → geometry

Returns a point along the given LineString which is at given fraction of LineString’s total length.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float, repeat: bool) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length. If repeat is false (default true) then it returns first point.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_linelocatepoint(line: geometry, point: geometry) → float

Returns a float between 0 and 1 representing the location of the closest point on LineString to the given Point, as a fraction of total 2d line length.

+		Immutable
st_linemerge(geometry: geometry) → geometry

Returns a LineString or MultiLineString by joining together constituents of a MultiLineString with matching endpoints. If the input is not a MultiLineString or LineString, an empty GeometryCollection is returned.

+

This function utilizes the GEOS module.

+		Immutable
st_linestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: decimal, end_fraction: decimal) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: float, end_fraction: float) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_longestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the max distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the maximum distance between the geometry’s vertexes. The function will return the longest line that was discovered first when comparing maximum distances if more than one is found.

+		Immutable
st_m(geometry: geometry) → float

Returns the M coordinate of a geometry if it is a Point.

+		Immutable
st_makebox2d(geometry_a: geometry, geometry_b: geometry) → box2d

Creates a box2d from two points. Errors if arguments are not two non-empty points.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with SRID 0.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float, srid: int) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with the given SRID.

+		Immutable
st_makepoint(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float) → geometry

Returns a new Point with the given X, Y, and Z coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float, m: float) → geometry

Returns a new Point with the given X, Y, Z, and M coordinates.

+		Immutable
st_makepointm(x: float, y: float, m: float) → geometry

Returns a new Point with the given X, Y, and M coordinates.

+		Immutable
st_makepolygon(geometry: geometry) → geometry

Returns a new Polygon with the given outer LineString.

+		Immutable
st_makepolygon(outer: geometry, interior: anyelement[]) → geometry

Returns a new Polygon with the given outer LineString and interior (hole) LineString(s).

+		Immutable
st_makevalid(geometry: geometry) → geometry

Returns a valid form of the given geometry according to the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_maxdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the maximum distance across every pair of points comprising the given geometries. Note if the geometries are the same, it will return the maximum distance between the geometry’s vertexes.

+		Immutable
st_memsize(geometry: geometry) → int

Returns the amount of memory space (in bytes) the geometry takes.

+		Immutable
st_minimumboundingcircle(geometry: geometry) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingcircle(geometry: geometry, num_segs: int) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingradius(geometry: geometry) → tuple{geometry AS center, float AS radius}

Returns a record containing the center point and radius of the smallest circle that can fully contains the given geometry.

+		Immutable
st_minimumclearance(geometry: geometry) → float

Returns the minimum distance a vertex can move before producing an invalid geometry. Returns Infinity if no minimum clearance can be found (e.g. for a single point).

+		Immutable
st_minimumclearanceline(geometry: geometry) → geometry

Returns a LINESTRING spanning the minimum distance a vertex can move before producing an invalid geometry. If no minimum clearance can be found (e.g. for a single point), an empty LINESTRING is returned.

+		Immutable
st_mlinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mlinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mpointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multi(geometry: geometry) → geometry

Returns the geometry as a new multi-geometry, e.g converts a POINT to a MULTIPOINT. If the input is already a multitype or collection, it is returned as is.

+		Immutable
st_multilinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multipointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_ndims(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_node(geometry: geometry) → geometry

Adds a node on a geometry for each intersection. Resulting geometry is always a MultiLineString.

+		Immutable
st_normalize(geometry: geometry) → geometry

Returns the geometry in its normalized form.

+

This function utilizes the GEOS module.

+		Immutable
st_npoints(geometry: geometry) → int

Returns the number of points in a given Geometry. Works for any shape type.

+		Immutable
st_nrings(geometry: geometry) → int

Returns the number of rings in a Polygon Geometry. Returns 0 if the shape is not a Polygon.

+		Immutable
st_numgeometries(geometry: geometry) → int

Returns the number of shapes inside a given Geometry.

+		Immutable
st_numinteriorring(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numinteriorrings(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numpoints(geometry: geometry) → int

Returns the number of points in a LineString. Returns NULL if the Geometry is not a LineString.

+		Immutable
st_orderingequals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is exactly equal to geometry_b, having all coordinates in the same order, as well as the same type, SRID, bounding box, and so on.

+		Immutable
st_orientedenvelope(geometry: geometry) → geometry

Returns a minimum rotated rectangle enclosing a geometry. +Note that more than one minimum rotated rectangle may exist. +May return a Point or LineString in the case of degenerate inputs.

+		Immutable
st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_perimeter(geography: geography) → float

Returns the perimeter of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geography: geography, use_spheroid: bool) → float

Returns the perimeter of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_perimeter2d(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_point(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_pointfromgeohash(geohash: string) → geometry

Return a POINT Geometry from a GeoHash string with max precision.

+		Immutable
st_pointfromgeohash(geohash: string, precision: int) → geometry

Return a POINT Geometry from a GeoHash string with supplied precision.

+		Immutable
st_pointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Point, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_pointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointinsidecircle(geometry: geometry, x_coord: float, y_coord: float, radius: float) → bool

Returns the true if the geometry is a point and is inside the circle. Returns false otherwise.

+		Immutable
st_pointn(geometry: geometry, n: int) → geometry

Returns the n-th Point of a LineString (1-indexed). Returns NULL if out of bounds or not a LineString.

+		Immutable
st_pointonsurface(geometry: geometry) → geometry

Returns a point that intersects with the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_points(geometry: geometry) → geometry

Returns all coordinates in the given Geometry as a MultiPoint, including duplicates.

+		Immutable
st_polyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygon(geometry: geometry, srid: int) → geometry

Returns a new Polygon from the given LineString and sets its SRID. It is equivalent to ST_MakePolygon with a single argument followed by ST_SetSRID.

+		Immutable
st_polygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_project(geography: geography, distance: float, azimuth: float) → geography

Returns a point projected from a start point along a geodesic using a given distance and azimuth (bearing). +This is known as the direct geodesic problem.

+

The distance is given in meters. Negative values are supported.

+

The azimuth (also known as heading or bearing) is given in radians. It is measured clockwise from true north (azimuth zero). +East is azimuth π/2 (90 degrees); south is azimuth π (180 degrees); west is azimuth 3π/2 (270 degrees). +Negative azimuth values and values greater than 2π (360 degrees) are supported.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, bnr: int) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b using the given boundary node rule (1:OGC/MOD2, 2:Endpoint, 3:MultivalentEndpoint, 4:MonovalentEndpoint).

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, pattern: string) → bool

Returns whether the DE-9IM spatial relation between geometry_a and geometry_b matches the DE-9IM pattern.

+

This function utilizes the GEOS module.

+		Immutable
st_relatematch(intersection_matrix: string, pattern: string) → bool

Returns whether the given DE-9IM intersection matrix satisfies the given pattern.

+		Immutable
st_removepoint(line_string: geometry, index: int) → geometry

Removes the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_removerepeatedpoints(geometry: geometry) → geometry

Returns a geometry with repeated points removed.

+		Immutable
st_removerepeatedpoints(geometry: geometry, tolerance: float) → geometry

Returns a geometry with repeated points removed, within the given distance tolerance.

+		Immutable
st_reverse(geometry: geometry) → geometry

Returns a modified geometry by reversing the order of its vertices.

+		Immutable
st_rotate(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_point: geometry) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_x: float, origin_y: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotatex(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the x axis by a rotation angle.

+		Immutable
st_rotatey(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the y axis by a rotation angle.

+		Immutable
st_rotatez(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the z axis by a rotation angle.

+		Immutable
st_s2covering(geography: geography) → geography

Returns a geography which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geography: geography, settings: string) → geography

Returns a geography which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geography, 's2_max_level=15,s2_level_mod=3').

+		Immutable
st_s2covering(geometry: geometry) → geometry

Returns a geometry which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geometry: geometry, settings: string) → geometry

Returns a geometry which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geometry, 's2_max_level=15,s2_level_mod=3')

+		Immutable
st_scale(g: geometry, factor: geometry) → geometry

Returns a modified Geometry scaled by taking in a Geometry as the factor.

+		Immutable
st_scale(g: geometry, factor: geometry, origin: geometry) → geometry

Returns a modified Geometry scaled by the Geometry factor relative to a false origin.

+		Immutable
st_scale(geometry: geometry, x_factor: float, y_factor: float) → geometry

Returns a modified Geometry scaled by the given factors.

+		Immutable
st_segmentize(geography: geography, max_segment_length_meters: float) → geography

Returns a modified Geography having no segment longer than the given max_segment_length meters.

+

The calculations are done on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_segmentize(geometry: geometry, max_segment_length: float) → geometry

Returns a modified Geometry having no segment longer than the given max_segment_length. Length units are in units of spatial reference.

+		Immutable
st_setpoint(line_string: geometry, index: int, point: geometry) → geometry

Sets the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_setsrid(geography: geography, srid: int) → geography

Sets a Geography to a new SRID without transforming the coordinates.

+		Immutable
st_setsrid(geometry: geometry, srid: int) → geometry

Sets a Geometry to a new SRID without transforming the coordinates.

+		Immutable
st_sharedpaths(geometry_a: geometry, geometry_b: geometry) → geometry

Returns a collection containing paths shared by the two input geometries.

+

Those going in the same direction are in the first element of the collection, +those going in the opposite direction are in the second element. +The paths themselves are given in the direction of the first geometry.

+		Immutable
st_shiftlongitude(geometry: geometry) → geometry

Returns a modified version of a geometry in which the longitude (X coordinate) of each point is incremented by 360 if it is <0 and decremented by 360 if it is >180. The result is only meaningful if the coordinates are in longitude/latitude.

+		Immutable
st_shortestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the minimum distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the minimum distance between the geometry’s vertexes. The function will return the shortest line that was discovered first when comparing minimum distances if more than one is found.

+		Immutable
st_simplify(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm.

+

This function utilizes the GEOS module.

+		Immutable
st_simplify(geometry: geometry, tolerance: float, preserve_collapsed: bool) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, retaining objects that would be too small given the tolerance if preserve_collapsed is set to true.

+		Immutable
st_simplifypreservetopology(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, avoiding the creation of invalid geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_snap(input: geometry, target: geometry, tolerance: float) → geometry

Snaps the vertices and segments of input geometry the target geometry’s vertices. +Tolerance is used to control where snapping is performed. The result geometry is the input geometry with the vertices snapped. +If no snapping occurs then the input geometry is returned unchanged.

+		Immutable
st_snaptogrid(geometry: geometry, origin: geometry, size_x: float, size_y: float, size_z: float, size_m: float) → geometry

Snap a geometry to a grid defined by the given origin and X, Y, Z, and M cell sizes. Any dimension with a 0 cell size will not be snapped.

+		Immutable
st_snaptogrid(geometry: geometry, origin_x: float, origin_y: float, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y based on an origin of (origin_x, origin_y).

+		Immutable
st_snaptogrid(geometry: geometry, size: float) → geometry

Snap a geometry to a grid of the given size. The specified size is only used to snap X and Y coordinates.

+		Immutable
st_snaptogrid(geometry: geometry, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y.

+		Immutable
st_srid(geography: geography) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geography as defined in spatial_ref_sys table.

+		Immutable
st_srid(geometry: geometry) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geometry as defined in spatial_ref_sys table.

+		Immutable
st_startpoint(geometry: geometry) → geometry

Returns the first point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_subdivide(geometry: geometry) → geometry

Returns a geometry divided into parts, where each part contains no more than 256 vertices.

+		Immutable
st_subdivide(geometry: geometry, max_vertices: int4) → geometry

Returns a geometry divided into parts, where each part contains no more than the number of vertices provided.

+		Immutable
st_summary(geography: geography) → string

Returns a text summary of the contents of the geography.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_summary(geometry: geometry) → string

Returns a text summary of the contents of the geometry.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_swapordinates(geometry: geometry, swap_ordinate_string: string) → geometry

Returns a version of the given geometry with given ordinates swapped. +The swap_ordinate_string parameter is a 2-character string naming the ordinates to swap. Valid names are: x, y, z and m.

+		Immutable
st_symdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_symmetricdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, srid: int) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates. The supplied SRID is set on the new geometry.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, srid: int) → geometry

Transforms a geometry into the given SRID coordinate reference system by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system referenced by the projection text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float, delta_z: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_transscale(geometry: geometry, delta_x: float, delta_y: float, x_factor: float, y_factor: float) → geometry

Translates the geometry using the deltaX and deltaY args, then scales it using the XFactor, YFactor args, working in 2D only.

+		Immutable
st_unaryunion(geometry: geometry) → geometry

Returns a union of the components for any geometry or geometry collection provided. Dissolves boundaries of a multipolygon.

+		Immutable
st_voronoilines(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoipolygons(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_wkbtosql(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_wkttosql(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_x(geometry: geometry) → float

Returns the X coordinate of a geometry if it is a Point.

+		Immutable
st_xmax(box2d: box2d) → float

Returns the maximum X ordinate of a box2d.

+		Immutable
st_xmax(geometry: geometry) → float

Returns the maximum X ordinate of a geometry.

+		Immutable
st_xmin(box2d: box2d) → float

Returns the minimum X ordinate of a box2d.

+		Immutable
st_xmin(geometry: geometry) → float

Returns the minimum X ordinate of a geometry.

+		Immutable
st_y(geometry: geometry) → float

Returns the Y coordinate of a geometry if it is a Point.

+		Immutable
st_ymax(box2d: box2d) → float

Returns the maximum Y ordinate of a box2d.

+		Immutable
st_ymax(geometry: geometry) → float

Returns the maximum Y ordinate of a geometry.

+		Immutable
st_ymin(box2d: box2d) → float

Returns the minimum Y ordinate of a box2d.

+		Immutable
st_ymin(geometry: geometry) → float

Returns the minimum Y ordinate of a geometry.

+		Immutable
st_z(geometry: geometry) → float

Returns the Z coordinate of a geometry if it is a Point.

+		Immutable
st_zmflag(geometry: geometry) → int2

Returns a code based on the ZM coordinate dimension of a geometry (XY = 0, XYM = 1, XYZ = 2, XYZM = 3).

+		Immutable
+ +### String and byte functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ascii(val: string) → int

Returns the character code of the first character in val. Despite the name, the function supports Unicode too.

+		Immutable
bit_length(val: bytes) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: string) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
bitmask_and(a: string, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: string, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
btrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning or end of input (applies recursively).

+

For example, btrim('doggie', 'eod') returns ggi.

+		Immutable
btrim(val: string) → string

Removes all spaces from the beginning and end of val.

+		Immutable
char_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
char_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
character_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
character_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
chr(val: int) → string

Returns the character with the code given in val. Inverse function of ascii().

+		Immutable
compress(data: bytes, codec: string) → bytes

Compress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
concat(string...) → string

Concatenates a comma-separated list of strings.

+		Immutable
concat_ws(string...) → string

Uses the first argument as a separator between the concatenation of the subsequent arguments.

+

For example concat_ws('!','wow','great') returns wow!great.

+		Immutable
convert_from(str: bytes, enc: string) → string

Decode the bytes in str into a string using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
convert_to(str: string, enc: string) → bytes

Encode the string str as a byte array using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
decode(text: string, format: string) → bytes

Decodes data using format (hex / escape / base64).

+		Immutable
decompress(data: bytes, codec: string) → bytes

Decompress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
difference(source: string, target: string) → int

Convert two strings to their Soundex codes and then reports the number of matching code positions.

+		Immutable
encode(data: bytes, format: string) → string

Encodes data using format (hex / escape / base64).

+		Immutable
format(string, anyelement...) → string

Interprets the first argument as a format string similar to C sprintf and interpolates the remaining arguments.

+		Stable
from_ip(val: bytes) → string

Converts the byte string representation of an IP to its character string representation.

+		Immutable
from_uuid(val: bytes) → string

Converts the byte string representation of a UUID to its character string representation.

+		Immutable
get_bit(bit_string: varbit, index: int) → int

Extracts a bit at given index in the bit array.

+		Immutable
get_bit(byte_string: bytes, index: int) → int

Extracts a bit at the given index in the byte array.

+		Immutable
get_byte(byte_string: bytes, index: int) → int

Extracts a byte at the given index in the byte array.

+		Immutable
initcap(val: string) → string

Capitalizes the first letter of val.

+		Immutable
left(input: bytes, return_set: int) → bytes

Returns the first return_set bytes from input.

+		Immutable
left(input: string, return_set: int) → string

Returns the first return_set characters from input.

+		Immutable
length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
length(val: string) → int

Calculates the number of characters in val.

+		Immutable
length(val: varbit) → int

Calculates the number of bits in val.

+		Immutable
lower(val: string) → string

Converts all characters in val to their lower-case equivalents.

+		Immutable
lpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the left of string.If string is longer than length it is truncated.

+		Immutable
lpad(string: string, length: int, fill: string) → string

Pads string by adding fill to the left of string to make it length. If string is longer than length it is truncated.

+		Immutable
ltrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning (left-hand side) of input (applies recursively).

+

For example, ltrim('doggie', 'od') returns ggie.

+		Immutable
ltrim(val: string) → string

Removes all spaces from the beginning (left-hand side) of val.

+		Immutable
md5(bytes...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
md5(string...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
octet_length(val: bytes) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: string) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int) → string

Replaces characters in input with overlay_val starting at start_pos (begins at 1).

+

For example, overlay('doggie', 'CAT', 2) returns dCATie.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int, end_pos: int) → string

Deletes the characters in input between start_pos and end_pos (count starts at 1), and then insert overlay_val at start_pos.

+		Immutable
parse_date(string: string, datestyle: string) → date

Parses a date assuming it is in format specified by DateStyle.

+		Immutable
parse_date(val: string) → date

Parses a date assuming it is in MDY format.

+		Immutable
parse_ident(qualified_identifier: string) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. Extra characters after the last identifier are considered an error

+		Immutable
parse_ident(qualified_identifier: string, strict: bool) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. If strict is false, then extra characters after the last identifier are ignored.

+		Immutable
parse_interval(string: string, style: string) → interval

Convert a string to an interval using the given IntervalStyle.

+		Immutable
parse_interval(val: string) → interval

Convert a string to an interval assuming the Postgres IntervalStyle.

+		Immutable
parse_time(string: string, timestyle: string) → time

Parses a time assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_time(val: string) → time

Parses a time assuming the date (if any) is in MDY format.

+		Immutable
parse_timestamp(string: string, datestyle: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates formatted using the given DateStyle.

+		Immutable
parse_timestamp(val: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates are in MDY format.

+		Immutable
parse_timetz(string: string, timestyle: string) → timetz

Parses a timetz assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_timetz(val: string) → timetz

Parses a timetz assuming the date (if any) is in MDY format.

+		Immutable
prettify_statement(statement: string, line_width: int, align_mode: int, case_mode: int) → string

Prettifies a statement using a user-configured pretty-printing config. +Align mode values range from 0 - 3, representing no, partial, full, and extra alignment respectively. +Case mode values range between 0 - 1, representing lower casing and upper casing respectively.

+		Immutable
prettify_statement(val: string) → string

Prettifies a statement using a the default pretty-printing config.

+		Immutable
quote_ident(val: string) → string

Return val suitably quoted to serve as identifier in a SQL statement.

+		Immutable
quote_literal(val: string) → string

Return val suitably quoted to serve as string literal in a SQL statement.

+		Immutable
quote_literal(val: anyelement) → string

Coerce val to a string and then quote it as a literal.

+		Stable
quote_nullable(val: string) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Immutable
quote_nullable(val: anyelement) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Stable
regexp_extract(input: string, regex: string) → string

Returns the first match for the Regular Expression regex in input.

+		Immutable
regexp_replace(input: string, regex: string, replace: string) → string

Replaces matches for the Regular Expression regex in input with the Regular Expression replace.

+		Immutable
regexp_replace(input: string, regex: string, replace: string, flags: string) → string

Replaces matches for the regular expression regex in input with the regular expression replace using flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
repeat(input: string, repeat_counter: int) → string

Concatenates input repeat_counter number of times.

+

For example, repeat('dog', 2) returns dogdog.

+		Immutable
replace(input: string, find: string, replace: string) → string

Replaces all occurrences of find with replace in input

+		Immutable
reverse(val: string) → string

Reverses the order of the string’s characters.

+		Immutable
right(input: bytes, return_set: int) → bytes

Returns the last return_set bytes from input.

+		Immutable
right(input: string, return_set: int) → string

Returns the last return_set characters from input.

+		Immutable
rpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the right of string. If string is longer than length it is truncated.

+		Immutable
rpad(string: string, length: int, fill: string) → string

Pads string to length by adding fill to the right of string. If string is longer than length it is truncated.

+		Immutable
rtrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the end (right-hand side) of input (applies recursively).

+

For example, rtrim('doggie', 'ei') returns dogg.

+		Immutable
rtrim(val: string) → string

Removes all spaces from the end (right-hand side) of val.

+		Immutable
set_bit(bit_string: varbit, index: int, to_set: int) → varbit

Updates a bit at given index in the bit array.

+		Immutable
set_bit(byte_string: bytes, index: int, to_set: int) → bytes

Updates a bit at the given index in the byte array.

+		Immutable
set_byte(byte_string: bytes, index: int, to_set: int) → bytes

Updates a byte at the given index in the byte array.

+		Immutable
sha1(bytes...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha1(string...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha224(bytes...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha224(string...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha256(bytes...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha256(string...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha384(bytes...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha384(string...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha512(bytes...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
sha512(string...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
similar_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_to_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
split_part(input: string, delimiter: string, return_index_pos: int) → string

Splits input on delimiter and return the value in the return_index_pos position (starting at 1).

+

For example, split_part('123.456.789.0','.',3)returns 789.

+		Immutable
strpos(input: bytes, find: bytes) → int

Calculates the position where the byte subarray find begins in input.

+		Immutable
strpos(input: string, find: string) → int

Calculates the position where the string find begins in input.

+

For example, strpos('doggie', 'gie') returns 4.

+		Immutable
strpos(input: varbit, find: varbit) → int

Calculates the position where the bit subarray find begins in input.

+		Immutable
substr(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substr(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substr(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substring(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substring(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
to_char_with_style(date: date, datestyle: string) → string

Convert an date to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_char_with_style(interval: interval, style: string) → string

Convert an interval to a string using the given IntervalStyle.

+		Immutable
to_char_with_style(timestamp: timestamp, datestyle: string) → string

Convert an timestamp to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_english(val: int) → string

This function enunciates the value of its argument using English cardinals.

+		Immutable
to_hex(val: bytes) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: int) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: string) → string

Converts val to its hexadecimal representation.

+		Immutable
to_ip(val: string) → bytes

Converts the character string representation of an IP to its byte string representation.

+		Immutable
to_uuid(val: string) → bytes

Converts the character string representation of a UUID to its byte string representation.

+		Immutable
translate(input: string, find: string, replace: string) → string

In input, replaces the first character from find with the first character in replace; repeat for each character in find.

+

For example, translate('doggie', 'dog', '123'); returns 1233ie.

+		Immutable
ulid_to_uuid(val: string) → uuid

Converts a ULID string to its UUID-encoded representation.

+		Immutable
unaccent(val: string) → string

Removes accents (diacritic signs) from the text provided in val.

+		Immutable
upper(val: string) → string

Converts all characters in val to their to their upper-case equivalents.

+		Immutable
+ +### System info functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cluster_logical_timestamp() → decimal

Returns the logical time of the current transaction as +a CockroachDB HLC in decimal form.

+

Note that uses of this function disable server-side optimizations and +may increase either contention or retry errors, or both.

+

Returns an error if run in a transaction with an isolation level weaker than SERIALIZABLE.

+		Volatile
current_database() → string

Returns the current database.

+		Stable
current_schema() → string

Returns the current schema.

+		Stable
current_schemas(include_pg_catalog: bool) → string[]

Returns the valid schemas in the search path.

+		Stable
current_user() → string

Returns the current user. This function is provided for compatibility with PostgreSQL.

+		Stable
session_user() → string

Returns the session user. This function is provided for compatibility with PostgreSQL.

+		Stable
to_regclass(text: string) → regtype

Translates a textual relation name to its OID

+		Stable
to_regnamespace(text: string) → regtype

Translates a textual schema name to its OID

+		Stable
to_regproc(text: string) → regtype

Translates a textual function or procedure name to its OID

+		Stable
to_regprocedure(text: string) → regtype

Translates a textual function or procedure name(with argument types) to its OID

+		Stable
to_regrole(text: string) → regtype

Translates a textual role name to its OID

+		Stable
to_regtype(text: string) → regtype

Translates a textual type name to its OID

+		Stable
version() → string

Returns the node’s version of CockroachDB.

+		Volatile
+ +### TIMETZ functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
current_time() → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time() → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_time(precision: int) → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time(precision: int) → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → timetz

Returns the current transaction’s time with time zone.

+		Stable
localtime(precision: int) → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime(precision: int) → timetz

Returns the current transaction’s time with time zone.

+		Stable
+ +### Trigrams functions + + + + + + +
Function → ReturnsDescriptionVolatility
show_trgm(input: string) → string[]

Returns an array of all the trigrams in the given string.

+		Immutable
similarity(left: string, right: string) → float

Returns a number that indicates how similar the two arguments are. The range of the result is zero (indicating that the two strings are completely dissimilar) to one (indicating that the two strings are identical).

+		Immutable
+ +### UUID functions + + + + + +
Function → ReturnsDescriptionVolatility
uuid_to_ulid(val: uuid) → string

Converts a UUID-encoded ULID to its string representation.

+		Immutable
+ +### Compatibility functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
col_description(table_oid: oid, column_number: int) → string

Returns the comment for a table column, which is specified by the OID of its table and its column number. (obj_description cannot be used for table columns, since columns do not have OIDs of their own.)

+		Stable
current_setting(setting_name: string) → string

System info

+		Stable
current_setting(setting_name: string, missing_ok: bool) → string

System info

+		Stable
format_type(type_oid: oid, typemod: int) → string

Returns the SQL name of a data type that is identified by its type OID and possibly a type modifier. Currently, the type modifier is ignored.

+		Stable
getdatabaseencoding() → string

Returns the current encoding name used by the database.

+		Stable
has_any_column_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_column_privilege(table: string, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: string, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_database_privilege(database: string, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(database: oid, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(user: string, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: string, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_foreign_data_wrapper_privilege(fdw: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(fdw: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_function_privilege(function: string, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(function: oid, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(user: string, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: string, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_language_privilege(language: string, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(language: oid, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(user: string, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: string, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_schema_privilege(schema: string, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(schema: oid, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_sequence_privilege(sequence: string, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(sequence: oid, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_server_privilege(server: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(server: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_table_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_tablespace_privilege(tablespace: string, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(tablespace: oid, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_type_privilege(type: string, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(type: oid, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(user: string, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: string, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
information_schema._pg_numeric_precision(typid: oid, typmod: int4) → int

Returns the precision of the given type with type modifier

+		Immutable
information_schema._pg_numeric_precision_radix(typid: oid, typmod: int4) → int

Returns the radix of the given type with type modifier

+		Immutable
information_schema._pg_numeric_scale(typid: oid, typmod: int4) → int

Returns the scale of the given type with type modifier

+		Immutable
nameconcatoid(name: string, oid: oid) → name

Used in the information_schema to produce specific_name columns, which are supposed to be unique per schema. The result is the same as ($1::text || ‘_’ || $2::text)::name except that, if it would not fit in 63 characters, we make it do so by truncating the name input (not the oid).

+		Immutable
obj_description(object_oid: oid) → string

Returns the comment for a database object specified by its OID alone. This is deprecated since there is no guarantee that OIDs are unique across different system catalogs; therefore, the wrong comment might be returned.

+		Stable
obj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a database object specified by its OID and the name of the containing system catalog. For example, obj_description(123456, ‘pg_class’) would retrieve the comment for the table with OID 123456.

+		Stable
oidvectortypes(vector: oidvector) → string

Generates a comma seperated string of type names from an oidvector.

+		Stable
pg_backend_pid() → int

Returns a numerical ID attached to this session. This ID is part of the query cancellation key used by the wire protocol. This function was only added for compatibility, and unlike in Postgres, the returned value does not correspond to a real process ID.

+		Stable
pg_collation_for(str: anyelement) → string

Returns the collation of the argument

+		Stable
pg_column_is_updatable(reloid: oid, attnum: int2, include_triggers: bool) → bool

Returns whether the given column can be updated.

+		Stable
pg_column_size(anyelement...) → int

Return size in bytes of the column provided as an argument

+		Immutable
pg_function_is_visible(oid: oid) → bool

Returns whether the function with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_get_function_arg_default(func_oid: oid, arg_num: int4) → string

Get textual representation of a function argument’s default value. The second argument of this function is the argument number among all arguments (i.e. proallargtypes, not proargtypes), starting with 1, because that’s how information_schema.sql uses it. Currently, this always returns NULL, since CockroachDB does not support default values.

+		Stable
pg_get_function_arguments(func_oid: oid) → string

Returns the argument list (with defaults) necessary to identify a function, in the form it would need to appear in within CREATE FUNCTION.

+		Stable
pg_get_function_identity_arguments(func_oid: oid) → string

Returns the argument list (without defaults) necessary to identify a function, in the form it would need to appear in within ALTER FUNCTION, for instance.

+		Stable
pg_get_function_result(func_oid: oid) → string

Returns the types of the result of the specified function.

+		Stable
pg_get_functiondef(func_oid: oid) → string

For user-defined functions, returns the definition of the specified function. For builtin functions, returns the name of the function.

+		Stable
pg_get_indexdef(index_oid: oid) → string

Gets the CREATE INDEX command for index

+		Stable
pg_get_indexdef(index_oid: oid, column_no: int, pretty_bool: bool) → string

Gets the CREATE INDEX command for index, or definition of just one index column when given a non-zero column number

+		Stable
pg_get_serial_sequence(table_name: string, column_name: string) → string

Returns the name of the sequence used by the given column_name in the table table_name.

+		Stable
pg_get_viewdef(view_oid: oid) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_get_viewdef(view_oid: oid, pretty_bool: bool) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_has_role(role: string, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(role: oid, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(user: string, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: string, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_is_other_temp_schema(oid: oid) → bool

Returns true if the given OID is the OID of another session’s temporary schema. (This can be useful, for example, to exclude other sessions’ temporary tables from a catalog display.)

+		Stable
pg_my_temp_schema() → oid

Returns the OID of the current session’s temporary schema, or zero if it has none (because it has not created any temporary tables).

+		Stable
pg_relation_is_updatable(reloid: oid, include_triggers: bool) → int4

Returns the update events the relation supports.

+		Stable
pg_sequence_last_value(sequence_oid: oid) → int

Returns the last value generated by a sequence, or NULL if the sequence has not been used yet.

+		Volatile
pg_sleep(seconds: float) → bool

pg_sleep makes the current session’s process sleep until seconds seconds have elapsed. seconds is a value of type double precision, so fractional-second delays can be specified.

+		Volatile
pg_table_is_visible(oid: oid) → bool

Returns whether the table with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_type_is_visible(oid: oid) → bool

Returns whether the type with the given OID belongs to one of the schemas on the search path.

+		Stable
set_config(setting_name: string, new_value: string, is_local: bool) → string

System info

+		Volatile
shobj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a shared database object specified by its OID and the name of the containing system catalog. This is just like obj_description except that it is used for retrieving comments on shared objects (e.g. databases).

+		Stable
+ diff --git a/src/current/_includes/cockroach-generated/release-23.2/sql/operators.md b/src/current/_includes/cockroach-generated/release-23.2/sql/operators.md new file mode 100644 index 00000000000..dde5d133a6c --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-23.2/sql/operators.md @@ -0,0 +1,635 @@ + + + + + +
#Return
int # intint
varbit # varbitvarbit
+ + + + +
#>Return
jsonb #> string[]jsonb
+ + + + +
#>>Return
jsonb #>> string[]string
+ + + + + + + + + +
%Return
decimal % decimaldecimal
decimal % intdecimal
float % floatfloat
int % decimaldecimal
int % intint
string % stringbool
+ + + + + + +
&Return
inet & inetinet
int & intint
varbit & varbitvarbit
+ + + + + + + + + +
&&Return
anyelement && anyelementbool
box2d && box2dbool
box2d && geometrybool
geometry && box2dbool
geometry && geometrybool
inet && inetbool
+ + + + + + + + + + + + + + +
*Return
decimal * decimaldecimal
decimal * intdecimal
decimal * intervalinterval
float * floatfloat
float * intervalinterval
int * decimaldecimal
int * intint
int * intervalinterval
interval * decimalinterval
interval * floatinterval
interval * intinterval
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Return
+decimaldecimal
+floatfloat
+intint
+intervalinterval
date + intdate
date + intervaltimestamp
date + timetimestamp
date + timetztimestamptz
decimal + decimaldecimal
decimal + intdecimal
decimal + pg_lsnpg_lsn
float + floatfloat
inet + intinet
int + datedate
int + decimaldecimal
int + inetinet
int + intint
interval + datetimestamp
interval + intervalinterval
interval + timetime
interval + timestamptimestamp
interval + timestamptztimestamptz
interval + timetztimetz
pg_lsn + decimalpg_lsn
time + datetimestamp
time + intervaltime
timestamp + intervaltimestamp
timestamptz + intervaltimestamptz
timetz + datetimestamptz
timetz + intervaltimetz
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
-Return
-decimaldecimal
-floatfloat
-intint
-intervalinterval
date - dateint
date - intdate
date - intervaltimestamp
date - timetimestamp
decimal - decimaldecimal
decimal - intdecimal
float - floatfloat
inet - inetint
inet - intinet
int - decimaldecimal
int - intint
interval - intervalinterval
jsonb - intjsonb
jsonb - stringjsonb
jsonb - string[]jsonb
pg_lsn - decimalpg_lsn
pg_lsn - pg_lsndecimal
time - intervaltime
time - timeinterval
timestamp - intervaltimestamp
timestamp - timestampinterval
timestamp - timestamptzinterval
timestamptz - intervaltimestamptz
timestamptz - timestampinterval
timestamptz - timestamptzinterval
timetz - intervaltimetz
+ + + + + +
->Return
jsonb -> intjsonb
jsonb -> stringjsonb
+ + + + + +
->>Return
jsonb ->> intstring
jsonb ->> stringstring
+ + + + + + + + + + +
/Return
decimal / decimaldecimal
decimal / intdecimal
float / floatfloat
int / decimaldecimal
int / intdecimal
interval / floatinterval
interval / intinterval
+ + + + + + + + +
//Return
decimal // decimaldecimal
decimal // intdecimal
float // floatfloat
int // decimaldecimal
int // intint
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<Return
anyenum < anyenumbool
bool < boolbool
bool[] < bool[]bool
box2d < box2dbool
bpchar < bpcharbool
bytes < bytesbool
bytes[] < bytes[]bool
collatedstring < collatedstringbool
date < datebool
date < timestampbool
date < timestamptzbool
date[] < date[]bool
decimal < decimalbool
decimal < floatbool
decimal < intbool
decimal[] < decimal[]bool
float < decimalbool
float < floatbool
float < intbool
float[] < float[]bool
geography < geographybool
geometry < geometrybool
inet < inetbool
inet[] < inet[]bool
int < decimalbool
int < floatbool
int < intbool
int < oidbool
int[] < int[]bool
interval < intervalbool
interval[] < interval[]bool
jsonb < jsonbbool
oid < intbool
oid < oidbool
pg_lsn < pg_lsnbool
refcursor < refcursorbool
string < stringbool
string[] < string[]bool
time < timebool
time < timetzbool
time[] < time[]bool
timestamp < datebool
timestamp < timestampbool
timestamp < timestamptzbool
timestamp[] < timestamp[]bool
timestamptz < datebool
timestamptz < timestampbool
timestamptz < timestamptzbool
timestamptz < timestamptzbool
timetz < timebool
timetz < timetzbool
tuple < tuplebool
uuid < uuidbool
uuid[] < uuid[]bool
varbit < varbitbool
+ + + + + + +
<<Return
inet << inetbool
int << intint
varbit << intvarbit
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<=Return
anyenum <= anyenumbool
bool <= boolbool
bool[] <= bool[]bool
box2d <= box2dbool
bpchar <= bpcharbool
bytes <= bytesbool
bytes[] <= bytes[]bool
collatedstring <= collatedstringbool
date <= datebool
date <= timestampbool
date <= timestamptzbool
date[] <= date[]bool
decimal <= decimalbool
decimal <= floatbool
decimal <= intbool
decimal[] <= decimal[]bool
float <= decimalbool
float <= floatbool
float <= intbool
float[] <= float[]bool
geography <= geographybool
geometry <= geometrybool
inet <= inetbool
inet[] <= inet[]bool
int <= decimalbool
int <= floatbool
int <= intbool
int <= oidbool
int[] <= int[]bool
interval <= intervalbool
interval[] <= interval[]bool
jsonb <= jsonbbool
oid <= intbool
oid <= oidbool
pg_lsn <= pg_lsnbool
refcursor <= refcursorbool
string <= stringbool
string[] <= string[]bool
time <= timebool
time <= timetzbool
time[] <= time[]bool
timestamp <= datebool
timestamp <= timestampbool
timestamp <= timestamptzbool
timestamp[] <= timestamp[]bool
timestamptz <= datebool
timestamptz <= timestampbool
timestamptz <= timestamptzbool
timestamptz <= timestamptzbool
timetz <= timebool
timetz <= timetzbool
tuple <= tuplebool
uuid <= uuidbool
uuid[] <= uuid[]bool
varbit <= varbitbool
+ + + + + +
<@Return
anyelement <@ anyelementbool
jsonb <@ jsonbbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
=Return
anyenum = anyenumbool
bool = boolbool
bool[] = bool[]bool
box2d = box2dbool
bpchar = bpcharbool
bytes = bytesbool
bytes[] = bytes[]bool
collatedstring = collatedstringbool
date = datebool
date = timestampbool
date = timestamptzbool
date[] = date[]bool
decimal = decimalbool
decimal = floatbool
decimal = intbool
decimal[] = decimal[]bool
float = decimalbool
float = floatbool
float = intbool
float[] = float[]bool
geography = geographybool
geometry = geometrybool
inet = inetbool
inet[] = inet[]bool
int = decimalbool
int = floatbool
int = intbool
int = oidbool
int[] = int[]bool
interval = intervalbool
interval[] = interval[]bool
jsonb = jsonbbool
oid = intbool
oid = oidbool
pg_lsn = pg_lsnbool
refcursor = refcursorbool
string = stringbool
string[] = string[]bool
time = timebool
time = timetzbool
time[] = time[]bool
timestamp = datebool
timestamp = timestampbool
timestamp = timestamptzbool
timestamp[] = timestamp[]bool
timestamptz = datebool
timestamptz = timestampbool
timestamptz = timestamptzbool
timestamptz = timestamptzbool
timetz = timebool
timetz = timetzbool
tsquery = tsquerybool
tsvector = tsvectorbool
tuple = tuplebool
uuid = uuidbool
uuid[] = uuid[]bool
varbit = varbitbool
+ + + + + + +
>>Return
inet >> inetbool
int >> intint
varbit >> intvarbit
+ + + + +
?Return
jsonb ? stringbool
+ + + + +
?&Return
jsonb ?& string[]bool
+ + + + +
?|Return
jsonb ?| string[]bool
+ + + + + +
@>Return
anyelement @> anyelementbool
jsonb @> jsonbbool
+ + + + + +
@@Return
tsquery @@ tsvectorbool
tsvector @@ tsquerybool
+ + + + +
ILIKEReturn
string ILIKE stringbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
INReturn
anyenum IN tuplebool
bool IN tuplebool
box2d IN tuplebool
bpchar IN tuplebool
bytes IN tuplebool
collatedstring IN tuplebool
date IN tuplebool
decimal IN tuplebool
float IN tuplebool
geography IN tuplebool
geometry IN tuplebool
inet IN tuplebool
int IN tuplebool
interval IN tuplebool
jsonb IN tuplebool
oid IN tuplebool
pg_lsn IN tuplebool
refcursor IN tuplebool
string IN tuplebool
time IN tuplebool
timestamp IN tuplebool
timestamptz IN tuplebool
timetz IN tuplebool
tuple IN tuplebool
uuid IN tuplebool
varbit IN tuplebool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IS NOT DISTINCT FROMReturn
anyelement IS NOT DISTINCT FROM unknownbool
anyenum IS NOT DISTINCT FROM anyenumbool
bool IS NOT DISTINCT FROM boolbool
bool[] IS NOT DISTINCT FROM bool[]bool
box2d IS NOT DISTINCT FROM box2dbool
bpchar IS NOT DISTINCT FROM bpcharbool
bytes IS NOT DISTINCT FROM bytesbool
bytes[] IS NOT DISTINCT FROM bytes[]bool
collatedstring IS NOT DISTINCT FROM collatedstringbool
date IS NOT DISTINCT FROM datebool
date IS NOT DISTINCT FROM timestampbool
date IS NOT DISTINCT FROM timestamptzbool
date[] IS NOT DISTINCT FROM date[]bool
decimal IS NOT DISTINCT FROM decimalbool
decimal IS NOT DISTINCT FROM floatbool
decimal IS NOT DISTINCT FROM intbool
decimal[] IS NOT DISTINCT FROM decimal[]bool
float IS NOT DISTINCT FROM decimalbool
float IS NOT DISTINCT FROM floatbool
float IS NOT DISTINCT FROM intbool
float[] IS NOT DISTINCT FROM float[]bool
geography IS NOT DISTINCT FROM geographybool
geometry IS NOT DISTINCT FROM geometrybool
inet IS NOT DISTINCT FROM inetbool
inet[] IS NOT DISTINCT FROM inet[]bool
int IS NOT DISTINCT FROM decimalbool
int IS NOT DISTINCT FROM floatbool
int IS NOT DISTINCT FROM intbool
int IS NOT DISTINCT FROM oidbool
int[] IS NOT DISTINCT FROM int[]bool
interval IS NOT DISTINCT FROM intervalbool
interval[] IS NOT DISTINCT FROM interval[]bool
jsonb IS NOT DISTINCT FROM jsonbbool
oid IS NOT DISTINCT FROM intbool
oid IS NOT DISTINCT FROM oidbool
pg_lsn IS NOT DISTINCT FROM pg_lsnbool
refcursor IS NOT DISTINCT FROM refcursorbool
string IS NOT DISTINCT FROM stringbool
string[] IS NOT DISTINCT FROM string[]bool
time IS NOT DISTINCT FROM timebool
time IS NOT DISTINCT FROM timetzbool
time[] IS NOT DISTINCT FROM time[]bool
timestamp IS NOT DISTINCT FROM datebool
timestamp IS NOT DISTINCT FROM timestampbool
timestamp IS NOT DISTINCT FROM timestamptzbool
timestamp[] IS NOT DISTINCT FROM timestamp[]bool
timestamptz IS NOT DISTINCT FROM datebool
timestamptz IS NOT DISTINCT FROM timestampbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timetz IS NOT DISTINCT FROM timebool
timetz IS NOT DISTINCT FROM timetzbool
tsquery IS NOT DISTINCT FROM tsquerybool
tsvector IS NOT DISTINCT FROM tsvectorbool
tuple IS NOT DISTINCT FROM tuplebool
unknown IS NOT DISTINCT FROM unknownbool
unknown IS NOT DISTINCT FROM voidbool
uuid IS NOT DISTINCT FROM uuidbool
uuid[] IS NOT DISTINCT FROM uuid[]bool
varbit IS NOT DISTINCT FROM varbitbool
void IS NOT DISTINCT FROM unknownbool
+ + + + +
LIKEReturn
string LIKE stringbool
+ + + + +
SIMILAR TOReturn
string SIMILAR TO stringbool
+ + + + + + + + +
^Return
decimal ^ decimaldecimal
decimal ^ intdecimal
float ^ floatfloat
int ^ decimaldecimal
int ^ intint
+ + + + + + +
|Return
inet | inetinet
int | intint
varbit | varbitvarbit
+ + + + + +
|/Return
|/decimaldecimal
|/floatfloat
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
||Return
bool || bool[]bool[]
bool || stringstring
bool[] || boolbool[]
bool[] || bool[]bool[]
box2d || box2dbox2d
box2d || stringstring
bytes || bytesbytes
bytes || bytes[]bytes[]
bytes[] || bytesbytes[]
bytes[] || bytes[]bytes[]
date || date[]date[]
date || stringstring
date[] || datedate[]
date[] || date[]date[]
decimal || decimal[]decimal[]
decimal || stringstring
decimal[] || decimaldecimal[]
decimal[] || decimal[]decimal[]
float || float[]float[]
float || stringstring
float[] || floatfloat[]
float[] || float[]float[]
geography || geographygeography
geography || stringstring
geometry || geometrygeometry
geometry || stringstring
inet || inet[]inet[]
inet || stringstring
inet[] || inetinet[]
inet[] || inet[]inet[]
int || int[]int[]
int || stringstring
int[] || intint[]
int[] || int[]int[]
interval || interval[]interval[]
interval || stringstring
interval[] || intervalinterval[]
interval[] || interval[]interval[]
jsonb || jsonbjsonb
jsonb || stringstring
oid || oidoid
oid || stringstring
pg_lsn || pg_lsnpg_lsn
pg_lsn || stringstring
refcursor || refcursorrefcursor
refcursor || stringstring
string || boolstring
string || box2dstring
string || datestring
string || decimalstring
string || floatstring
string || geographystring
string || geometrystring
string || inetstring
string || intstring
string || intervalstring
string || jsonbstring
string || oidstring
string || pg_lsnstring
string || refcursorstring
string || stringstring
string || string[]string[]
string || timestring
string || timestampstring
string || timestamptzstring
string || timetzstring
string || tuplestring
string || uuidstring
string || varbitstring
string[] || stringstring[]
string[] || string[]string[]
time || stringstring
time || time[]time[]
time[] || timetime[]
time[] || time[]time[]
timestamp || stringstring
timestamp || timestamp[]timestamp[]
timestamp[] || timestamptimestamp[]
timestamp[] || timestamp[]timestamp[]
timestamptz || stringstring
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timetz || stringstring
timetz || timetztimetz
tuple || stringstring
uuid || stringstring
uuid || uuid[]uuid[]
uuid[] || uuiduuid[]
uuid[] || uuid[]uuid[]
varbit || stringstring
varbit || varbitvarbit
+ + + + + +
||/Return
||/decimaldecimal
||/floatfloat
+ + + + + + + + + + + +
~Return
~inetinet
~intint
~varbitvarbit
box2d ~ box2dbool
box2d ~ geometrybool
geometry ~ box2dbool
geometry ~ geometrybool
string ~ stringbool
+ + + + +
~*Return
string ~* stringbool
diff --git a/src/current/_includes/cockroach-generated/release-23.2/sql/window_functions.md b/src/current/_includes/cockroach-generated/release-23.2/sql/window_functions.md new file mode 100644 index 00000000000..e1032ff82de --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-23.2/sql/window_functions.md @@ -0,0 +1,413 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cume_dist() → float

Calculates the relative rank of the current row: (number of rows preceding or peer with current row) / (total rows).

+		Immutable
dense_rank() → int

Calculates the rank of the current row without gaps; this function counts peer groups.

+		Immutable
first_value(val: bool) → bool

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: bytes) → bytes

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: date) → date

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: decimal) → decimal

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: float) → float

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: inet) → inet

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: int) → int

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: interval) → interval

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: string) → string

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: time) → time

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: uuid) → uuid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: box2d) → box2d

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geography) → geography

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geometry) → geometry

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: oid) → oid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timetz) → timetz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: varbit) → varbit

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
lag(val: bool) → bool

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: bytes) → bytes

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: date) → date

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: date, n: int) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: decimal) → decimal

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: float) → float

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: float, n: int) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: inet) → inet

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: int) → int

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: int, n: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: interval) → interval

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: string) → string

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: string, n: int) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: time) → time

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: time, n: int) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamp) → timestamp

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz) → timestamptz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: uuid) → uuid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: box2d) → box2d

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geography) → geography

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geometry) → geometry

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: jsonb) → jsonb

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: oid) → oid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn) → pg_lsn

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: refcursor) → refcursor

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timetz) → timetz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: varbit) → varbit

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
last_value(val: bool) → bool

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: bytes) → bytes

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: date) → date

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: decimal) → decimal

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: float) → float

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: inet) → inet

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: int) → int

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: interval) → interval

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: string) → string

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: time) → time

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: uuid) → uuid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: box2d) → box2d

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geography) → geography

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geometry) → geometry

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: oid) → oid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timetz) → timetz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: varbit) → varbit

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
lead(val: bool) → bool

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: bytes) → bytes

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: date) → date

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: date, n: int) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: decimal) → decimal

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: float) → float

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: float, n: int) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: inet) → inet

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: int) → int

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: int, n: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: interval) → interval

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: string) → string

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: string, n: int) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: time) → time

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: time, n: int) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamp) → timestamp

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz) → timestamptz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: uuid) → uuid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: box2d) → box2d

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geography) → geography

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geometry) → geometry

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: jsonb) → jsonb

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: oid) → oid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn) → pg_lsn

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: refcursor) → refcursor

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timetz) → timetz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: varbit) → varbit

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
nth_value(val: bool, n: int) → bool

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: bytes, n: int) → bytes

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: date, n: int) → date

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: decimal, n: int) → decimal

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: float, n: int) → float

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: inet, n: int) → inet

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: int, n: int) → int

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: interval, n: int) → interval

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: string, n: int) → string

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: time, n: int) → time

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: uuid, n: int) → uuid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: box2d, n: int) → box2d

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geography, n: int) → geography

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geometry, n: int) → geometry

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: oid, n: int) → oid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timetz, n: int) → timetz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: varbit, n: int) → varbit

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
ntile(n: int) → int

Calculates an integer ranging from 1 to n, dividing the partition as equally as possible.

+		Immutable
percent_rank() → float

Calculates the relative rank of the current row: (rank - 1) / (total rows - 1).

+		Immutable
rank() → int

Calculates the rank of the current row with gaps; same as row_number of its first peer.

+		Immutable
row_number() → int

Calculates the number of the current row within its partition, counting from 1.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-24.1/eventlog.md b/src/current/_includes/cockroach-generated/release-24.1/eventlog.md new file mode 100644 index 00000000000..f7012dc84be --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.1/eventlog.md @@ -0,0 +1,3290 @@ +Certain notable events are reported using a structured format. +Commonly, these notable events are also copied to the table +`system.eventlog`, unless the cluster setting +`server.eventlog.enabled` is unset. + +Additionally, notable events are copied to specific external logging +channels in log messages, where they can be collected for further processing. + +The sections below document the possible notable event types +in this version of CockroachDB. For each event type, a table +documents the possible fields. A field may be omitted from +an event if its value is empty or zero. + +A field is also considered "Sensitive" if it may contain +application-specific information or personally identifiable information (PII). In that case, +the copy of the event sent to the external logging channel +will contain redaction markers in a format that is compatible +with the redaction facilities in [`cockroach debug zip`](cockroach-debug-zip.html) +and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html), +provided the `redactable` functionality is enabled on the logging sink. + +Events not documented on this page will have an unstructured format in log messages. + +## Cluster-level events + +Events in this category pertain to an entire cluster and are +not relative to any particular tenant. + +In a multi-tenant setup, the `system.eventlog` table for individual +tenants cannot contain a copy of cluster-level events; conversely, +the `system.eventlog` table in the system tenant cannot contain the +SQL-level events for individual tenants. + +Events in this category are logged to the `OPS` channel. + + +### `certs_reload` + +An event of type `certs_reload` is recorded when the TLS certificates are +reloaded/rotated from disk. + + +| Field | Description | Sensitive | +|--|--|--| +| `Success` | Whether the operation completed without errors. | no | +| `ErrorMessage` | If an error was encountered, the text of the error. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `node_decommissioned` + +An event of type `node_decommissioned` is recorded when a node is marked as +decommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_decommissioning` + +An event of type `node_decommissioning` is recorded when a node is marked as +decommissioning. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_join` + +An event of type `node_join` is recorded when a node joins the cluster. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_recommissioned` + +An event of type `node_recommissioned` is recorded when a decommissioning node is +recommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_restart` + +An event of type `node_restart` is recorded when an existing node rejoins the cluster +after being offline. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_connection_timeout` + +An event of type `node_shutdown_connection_timeout` is recorded when SQL connections remain open +during shutdown, after waiting for the server.shutdown.connections.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still open after waiting for the client to close them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.connections.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_transaction_timeout` + +An event of type `node_shutdown_transaction_timeout` is recorded when SQL transactions remain open +during shutdown, after waiting for the server.shutdown.transactions.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still running SQL transactions after waiting for the client to end them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.transactions.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `tenant_shared_service_start` + +An event of type `tenant_shared_service_start` is recorded when a tenant server +is started inside the same process as the KV layer. + + +| Field | Description | Sensitive | +|--|--|--| +| `OK` | Whether the startup was successful. | no | +| `ErrorText` | If the startup failed, the text of the error. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +### `tenant_shared_service_stop` + +An event of type `tenant_shared_service_stop` is recorded when a tenant server +is shut down inside the same process as the KV layer. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +## Debugging events + +Events in this category pertain to debugging operations performed by +operators or (more commonly) Cockroach Labs employees. These operations can +e.g. directly access and mutate internal state, breaking system invariants. + +Events in this category are logged to the `OPS` channel. + + +### `debug_recover_replica` + +An event of type `debug_recover_replica` is recorded when unsafe loss of quorum recovery is performed. + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `StoreID` | | no | +| `SurvivorReplicaID` | | no | +| `UpdatedReplicaID` | | no | +| `StartKey` | | yes | +| `EndKey` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +### `debug_send_kv_batch` + +An event of type `debug_send_kv_batch` is recorded when an arbitrary KV BatchRequest is submitted +to the cluster via the `debug send-kv-batch` CLI command. + + +| Field | Description | Sensitive | +|--|--|--| +| `BatchRequest` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +## Health events + +Events in this category pertain to the health of one or more servers. + +Events in this category are logged to the `HEALTH` channel. + + +### `runtime_stats` + +An event of type `runtime_stats` is recorded every 10 seconds as server health metrics. + + +| Field | Description | Sensitive | +|--|--|--| +| `MemRSSBytes` | The process resident set size. Expressed as bytes. | no | +| `GoroutineCount` | The number of goroutines. | no | +| `MemStackSysBytes` | The stack system memory used. Expressed as bytes. | no | +| `GoAllocBytes` | The memory allocated by Go. Expressed as bytes. | no | +| `GoTotalBytes` | The total memory allocated by Go but not released. Expressed as bytes. | no | +| `GoStatsStaleness` | The staleness of the Go memory statistics. Expressed in seconds. | no | +| `HeapFragmentBytes` | The amount of heap fragmentation. Expressed as bytes. | no | +| `HeapReservedBytes` | The amount of heap reserved. Expressed as bytes. | no | +| `HeapReleasedBytes` | The amount of heap released. Expressed as bytes. | no | +| `CGoAllocBytes` | The memory allocated outside of Go. Expressed as bytes. | no | +| `CGoTotalBytes` | The total memory allocated outside of Go but not released. Expressed as bytes. | no | +| `CGoCallRate` | The total number of calls outside of Go over time. Expressed as operations per second. | no | +| `CPUUserPercent` | The user CPU percentage. | no | +| `CPUSysPercent` | The system CPU percentage. | no | +| `GCPausePercent` | The GC pause percentage. | no | +| `GCRunCount` | The total number of GC runs. | no | +| `NetHostRecvBytes` | The bytes received on all network interfaces since this process started. | no | +| `NetHostSendBytes` | The bytes sent on all network interfaces since this process started. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Job events + +Events in this category pertain to long-running jobs that are orchestrated by +a node's job registry. These system processes can create and/or modify stored +objects during the course of their execution. + +A job might choose to emit multiple events during its execution when +transitioning from one "state" to another. +Egs: IMPORT/RESTORE will emit events on job creation and successful +completion. If the job fails, events will be emitted on job creation, +failure, and successful revert. + +Events in this category are logged to the `OPS` channel. + + +### `import` + +An event of type `import` is recorded when an import job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `restore` + +An event of type `restore` is recorded when a restore job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +## Miscellaneous SQL events + +Events in this category report miscellaneous SQL events. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own system.eventlog table. + +Events in this category are logged to the `OPS` channel. + + +### `set_cluster_setting` + +An event of type `set_cluster_setting` is recorded when a cluster setting is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `set_tenant_cluster_setting` + +An event of type `set_tenant_cluster_setting` is recorded when a cluster setting override +is changed, either for another tenant or for all tenants. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | +| `TenantId` | The target Tenant ID. Empty if targeting all tenants. | no | +| `AllTenants` | Whether the override applies to all tenants. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +## SQL Access Audit Events + +Events in this category are generated when a table has been +marked as audited via `ALTER TABLE ... EXPERIMENTAL_AUDIT SET`. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SENSITIVE_ACCESS` channel. + + +### `admin_query` + +An event of type `admin_query` is recorded when a user with admin privileges (the user +is directly or indirectly a member of the admin role) executes a query. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `role_based_audit_event` + +An event of type `role_based_audit_event` is an audit event recorded when an executed query belongs to a user whose role +membership(s) correspond to any role that is enabled to emit an audit log via the sql.log.user_audit +cluster setting. + + +| Field | Description | Sensitive | +|--|--|--| +| `Role` | The configured audit role that emitted this log. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sensitive_table_access` + +An event of type `sensitive_table_access` is recorded when an access is performed to +a table marked as audited. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table being audited. | yes | +| `AccessMode` | How the table was accessed (r=read / rw=read/write). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +## SQL Execution Log + +Events in this category report executed queries. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `query_execute` + +An event of type `query_execute` is recorded when a query is executed, +and the cluster setting `sql.log.all_statements.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +## SQL Logical Schema Changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the SQL logical +schema. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SQL_SCHEMA` channel. + + +### `alter_database_add_region` + +An event of type `alter_database_add_region` is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | yes | +| `RegionName` | The region being added. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_drop_region` + +AlterDatabaseAddRegion is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | yes | +| `RegionName` | The region being dropped. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_placement` + +An event of type `alter_database_placement` is recorded when the database placement is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | yes | +| `Placement` | The new placement policy. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_primary_region` + +An event of type `alter_database_primary_region` is recorded when a primary region is added/modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | yes | +| `PrimaryRegionName` | The new primary region. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_set_zone_config_extension` + +An event of type `alter_database_set_zone_config_extension` is recorded when a zone config extension is changed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `alter_database_survival_goal` + +An event of type `alter_database_survival_goal` is recorded when the survival goal is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | yes | +| `SurvivalGoal` | The new survival goal | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_function_options` + +An event of type `alter_function_options` is recorded when a user-defined function's options are +altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the affected function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_index` + +An event of type `alter_index` is recorded when an index is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | yes | +| `IndexName` | The name of the affected index. | yes | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_index_visible` + +AlterIndex is recorded when an index visibility is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | yes | +| `IndexName` | The name of the affected index. | yes | +| `NotVisible` | Set true if index is not visible. NOTE: THIS FIELD IS DEPRECATED in favor of invisibility. | no | +| `Invisibility` | The new invisibility of the affected index. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_sequence` + +An event of type `alter_sequence` is recorded when a sequence is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_table` + +An event of type `alter_table` is recorded when a table is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update, if any. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_type` + +EventAlterType is recorded when a user-defined type is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_column` + +An event of type `comment_on_column` is recorded when a column is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected column. | yes | +| `ColumnName` | The affected column. | yes | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_constraint` + +An event of type `comment_on_constraint` is recorded when an constraint is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected constraint. | yes | +| `ConstraintName` | The name of the affected constraint. | yes | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_database` + +CommentOnTable is recorded when a database is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_index` + +An event of type `comment_on_index` is recorded when an index is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | yes | +| `IndexName` | The name of the affected index. | yes | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_schema` + + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | Name of the affected schema. | yes | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_table` + +An event of type `comment_on_table` is recorded when a table is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_database` + +An event of type `create_database` is recorded when a database is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the new database. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_function` + +An event of type `create_function` is recorded when a user-defined function is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the created function. | yes | +| `IsReplace` | If the new function is a replace of an existing function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_index` + +An event of type `create_index` is recorded when an index is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the new index. | yes | +| `IndexName` | The name of the new index. | yes | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_schema` + +An event of type `create_schema` is recorded when a schema is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the new schema. | yes | +| `Owner` | The name of the owner for the new schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_sequence` + +An event of type `create_sequence` is recorded when a sequence is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the new sequence. | yes | +| `Owner` | The name of the owner for the new sequence. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_statistics` + +An event of type `create_statistics` is recorded when statistics are collected for a +table. + +Events of this type are only collected when the cluster setting +`sql.stats.post_events.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table for which the statistics were created. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_table` + +An event of type `create_table` is recorded when a table is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the new table. | yes | +| `Owner` | The name of the owner for the new table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_type` + +An event of type `create_type` is recorded when a user-defined type is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the new type. | yes | +| `Owner` | The name of the owner for the new type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_view` + +An event of type `create_view` is recorded when a view is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the new view. | yes | +| `Owner` | The name of the owner of the new view. | yes | +| `ViewQuery` | The SQL selection clause used to define the view. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_database` + +An event of type `drop_database` is recorded when a database is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | +| `DroppedSchemaObjects` | The names of the schemas dropped by a cascade operation. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_function` + +An event of type `drop_function` is recorded when a user-defined function is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the created function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_index` + +An event of type `drop_index` is recorded when an index is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | yes | +| `IndexName` | The name of the affected index. | yes | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_schema` + +An event of type `drop_schema` is recorded when a schema is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_sequence` + +An event of type `drop_sequence` is recorded when a sequence is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_table` + +An event of type `drop_table` is recorded when a table is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_type` + +An event of type `drop_type` is recorded when a user-defined type is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_view` + +An event of type `drop_view` is recorded when a view is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the affected view. | yes | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `finish_schema_change` + +An event of type `finish_schema_change` is recorded when a previously initiated schema +change has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to complete. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `finish_schema_change_rollback` + +An event of type `finish_schema_change_rollback` is recorded when a previously +initiated schema change rollback has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to rollback. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `force_delete_table_data_entry` + + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_database` + +An event of type `rename_database` is recorded when a database is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The old name of the affected database. | yes | +| `NewDatabaseName` | The new name of the affected database. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_function` + +An event of type `rename_function` is recorded when a user-defined function is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The old name of the affected function. | yes | +| `NewFunctionName` | The new name of the affected function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_schema` + +An event of type `rename_schema` is recorded when a schema is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The old name of the affected schema. | yes | +| `NewSchemaName` | The new name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_table` + +An event of type `rename_table` is recorded when a table, sequence or view is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The old name of the affected table. | yes | +| `NewTableName` | The new name of the affected table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_type` + +An event of type `rename_type` is recorded when a user-defined type is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The old name of the affected type. | yes | +| `NewTypeName` | The new name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `reverse_schema_change` + +An event of type `reverse_schema_change` is recorded when an in-progress schema change +encounters a problem and is reversed. + + +| Field | Description | Sensitive | +|--|--|--| +| `Error` | The error encountered that caused the schema change to be reversed. The specific format of the error is variable and can change across releases without warning. | yes | +| `SQLSTATE` | The SQLSTATE code for the error. | no | +| `LatencyNanos` | The amount of time the schema change job took before being reverted. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `set_schema` + +An event of type `set_schema` is recorded when a table, view, sequence or type's schema is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorName` | The old name of the affected descriptor. | yes | +| `NewDescriptorName` | The new name of the affected descriptor. | yes | +| `DescriptorType` | The descriptor type being changed (table, view, sequence, type). | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `truncate_table` + +An event of type `truncate_table` is recorded when a table is truncated. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_delete_descriptor` + +An event of type `unsafe_delete_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_delete_descriptor(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | yes | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_delete_namespace_entry` + +An event of type `unsafe_delete_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_delete_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | yes | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_upsert_descriptor` + +An event of type `unsafe_upsert_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_upsert_descriptor(). + + +| Field | Description | Sensitive | +|--|--|--| +| `PreviousDescriptor` | | yes | +| `NewDescriptor` | | yes | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_upsert_namespace_entry` + +An event of type `unsafe_upsert_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_upsert_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | yes | +| `PreviousID` | | no | +| `Force` | | no | +| `FailedValidation` | | no | +| `ValidationErrors` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +## SQL Privilege changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the privilege +grants for stored objects. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `PRIVILEGES` channel. + + +### `alter_database_owner` + +An event of type `alter_database_owner` is recorded when a database's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database being affected. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_default_privileges` + +An event of type `alter_default_privileges` is recorded when default privileges are changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | +| `RoleName` | Either role_name should be populated or for_all_roles should be true. The role having its default privileges altered. | yes | +| `ForAllRoles` | Identifies if FOR ALL ROLES is used. | no | +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `alter_function_owner` + +AlterTableOwner is recorded when the owner of a user-defined function is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The name of the affected user-defined function. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_schema_owner` + +An event of type `alter_schema_owner` is recorded when a schema's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_table_owner` + +An event of type `alter_table_owner` is recorded when the owner of a table, view or sequence is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected object. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_type_owner` + +An event of type `alter_type_owner` is recorded when the owner of a user-defiend type is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `change_database_privilege` + +An event of type `change_database_privilege` is recorded when privileges are +added to / removed from a user for a database object. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_function_privilege` + + + +| Field | Description | Sensitive | +|--|--|--| +| `FuncName` | The name of the affected function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_schema_privilege` + +An event of type `change_schema_privilege` is recorded when privileges are added to / +removed from a user for a schema object. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_table_privilege` + +An event of type `change_table_privilege` is recorded when privileges are added to / removed +from a user for a table, sequence or view object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_type_privilege` + +An event of type `change_type_privilege` is recorded when privileges are added to / +removed from a user for a type object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +## SQL Session events + +Events in this category report SQL client connections +and sessions. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SESSIONS` channel. + + +### `client_authentication_failed` + +An event of type `client_authentication_failed` is reported when a client session +did not authenticate successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Reason` | The reason for the authentication failure. See below for possible values for type `AuthFailReason`. | no | +| `Detail` | The detailed error for the authentication failure. | partially | +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_info` + +An event of type `client_authentication_info` is reported for intermediate +steps during the authentication process. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used, once known. | no | +| `Info` | The authentication progress message. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_ok` + +An event of type `client_authentication_ok` is reported when a client session +was authenticated successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_connection_end` + +An event of type `client_connection_end` is reported when a client connection +is closed. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_connection_start` + +An event of type `client_connection_start` is reported when a client connection +is established. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_session_end` + +An event of type `client_session_end` is reported when a client session +is completed. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +## SQL Slow Query Log + +Events in this category report slow query execution. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_PERF` channel. + + +### `large_row` + +An event of type `large_row` is recorded when a statement tries to write a row larger than +cluster setting `sql.guardrails.max_row_size_log` to the database. Multiple +LargeRow events will be recorded for statements writing multiple large rows. +LargeRow events are recorded before the transaction commits, so in the case +of transaction abort there will not be a corresponding row in the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query` + +An event of type `slow_query` is recorded when a query triggers the "slow query" condition. + +As of this writing, the condition requires: +- the cluster setting `sql.log.slow_query.latency_threshold` +set to a non-zero value, AND +- EITHER of the following conditions: +- the actual age of the query exceeds the configured threshold; AND/OR +- the query performs a full table/index scan AND the cluster setting +`sql.log.slow_query.experimental_full_table_scans.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit` + +An event of type `txn_rows_read_limit` is recorded when a transaction tries to read more rows than +cluster setting `sql.defaults.transaction_rows_read_log`. There will only be +a single record for a single transaction (unless it is retried) even if there +are more statement within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit` + +An event of type `txn_rows_written_limit` is recorded when a transaction tries to write more rows +than cluster setting `sql.defaults.transaction_rows_written_log`. There will +only be a single record for a single transaction (unless it is retried) even +if there are more mutation statements within the transaction that haven't +been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL Slow Query Log (Internal) + +Events in this category report slow query execution by +internal executors, i.e., when CockroachDB internally issues +SQL statements. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_INTERNAL_PERF` channel. + + +### `large_row_internal` + +An event of type `large_row_internal` is recorded when an internal query tries to write a row +larger than cluster settings `sql.guardrails.max_row_size_log` or +`sql.guardrails.max_row_size_err` to the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query_internal` + +An event of type `slow_query_internal` is recorded when a query triggers the "slow query" condition, +and the cluster setting `sql.log.slow_query.internal_queries.enabled` is +set. +See the documentation for the event type `slow_query` for details about +the "slow query" condition. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit_internal` + +An event of type `txn_rows_read_limit_internal` is recorded when an internal transaction tries to +read more rows than cluster setting `sql.defaults.transaction_rows_read_log` +or `sql.defaults.transaction_rows_read_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit_internal` + +An event of type `txn_rows_written_limit_internal` is recorded when an internal transaction tries to +write more rows than cluster setting +`sql.defaults.transaction_rows_written_log` or +`sql.defaults.transaction_rows_written_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL User and Role operations + +Events in this category pertain to SQL statements that modify the +properties of users and roles. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `USER_ADMIN` channel. + + +### `alter_role` + +An event of type `alter_role` is recorded when a role is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | +| `Options` | The options set on the user/role. | no | +| `SetInfo` | Information corresponding to an ALTER ROLE SET statement. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_role` + +An event of type `create_role` is recorded when a role is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the new user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_role` + +An event of type `drop_role` is recorded when a role is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `grant_role` + +An event of type `grant_role` is recorded when a role is granted. + + +| Field | Description | Sensitive | +|--|--|--| +| `GranteeRoles` | The roles being granted to. | yes | +| `Members` | The roles being granted. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `password_hash_converted` + +An event of type `password_hash_converted` is recorded when the password credentials +are automatically converted server-side. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the user/role whose credentials have been converted. | yes | +| `OldMethod` | The previous hash method. | no | +| `NewMethod` | The new hash method. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Storage telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `level_stats` + +An event of type `level_stats` contains per-level statistics for an LSM. + + +| Field | Description | Sensitive | +|--|--|--| +| `Level` | level is the level ID in a LSM (e.g. level(L0) == 0, etc.) | no | +| `NumFiles` | num_files is the number of files in the level (gauge). | no | +| `SizeBytes` | size_bytes is the size of the level, in bytes (gauge). | no | +| `Score` | score is the compaction score of the level (gauge). | no | +| `BytesIn` | bytes_in is the number of bytes written to this level (counter). | no | +| `BytesIngested` | bytes_ingested is the number of bytes ingested into this level (counter). | no | +| `BytesMoved` | bytes_moved is the number of bytes moved into this level via a move-compaction (counter). | no | +| `BytesRead` | bytes_read is the number of bytes read from this level, during compactions (counter). | no | +| `BytesCompacted` | bytes_compacted is the number of bytes written to this level during compactions (counter). | no | +| `BytesFlushed` | bytes flushed is the number of bytes flushed to this level. This value is always zero for levels other than L0 (counter). | no | +| `TablesCompacted` | tables_compacted is the count of tables compacted into this level (counter). | no | +| `TablesFlushed` | tables_flushed is the count of tables flushed into this level (counter). | no | +| `TablesIngested` | tables_ingested is the count of tables ingested into this level (counter). | no | +| `TablesMoved` | tables_moved is the count of tables moved into this level via move-compactions (counter). | no | +| `NumSublevels` | num_sublevel is the count of sublevels for the level. This value is always zero for levels other than L0 (gauge). | no | + + + +### `store_stats` + +An event of type `store_stats` contains per store stats. + +Note that because stats are scoped to the lifetime of the process, counters +(and certain gauges) will be reset across node restarts. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeId` | node_id is the ID of the node. | no | +| `StoreId` | store_id is the ID of the store. | no | +| `Levels` | levels is a nested message containing per-level statistics. | yes | +| `CacheSize` | cache_size is the size of the cache for the store, in bytes (gauge). | no | +| `CacheCount` | cache_count is the number of items in the cache (gauge). | no | +| `CacheHits` | cache_hits is the number of cache hits (counter). | no | +| `CacheMisses` | cache_misses is the number of cache misses (counter). | no | +| `CompactionCountDefault` | compaction_count_default is the count of default compactions (counter). | no | +| `CompactionCountDeleteOnly` | compaction_count_delete_only is the count of delete-only compactions (counter). | no | +| `CompactionCountElisionOnly` | compaction_count_elision_only is the count of elision-only compactions (counter). | no | +| `CompactionCountMove` | compaction_count_move is the count of move-compactions (counter). | no | +| `CompactionCountRead` | compaction_count_read is the count of read-compactions (counter). | no | +| `CompactionCountRewrite` | compaction_count_rewrite is the count of rewrite-compactions (counter). | no | +| `CompactionNumInProgress` | compactions_num_in_progress is the number of compactions in progress (gauge). | no | +| `CompactionMarkedFiles` | compaction_marked_files is the count of files marked for compaction (gauge). | no | +| `FlushCount` | flush_count is the number of flushes (counter). | no | +| `FlushIngestCount` | | no | +| `FlushIngestTableCount` | | no | +| `FlushIngestTableBytes` | | no | +| `IngestCount` | ingest_count is the number of successful ingest operations (counter). | no | +| `MemtableSize` | memtable_size is the total size allocated to all memtables and (large) batches, in bytes (gauge). | no | +| `MemtableCount` | memtable_count is the count of memtables (gauge). | no | +| `MemtableZombieCount` | memtable_zombie_count is the count of memtables no longer referenced by the current DB state, but still in use by an iterator (gauge). | no | +| `MemtableZombieSize` | memtable_zombie_size is the size, in bytes, of all zombie memtables (gauge). | no | +| `WalLiveCount` | wal_live_count is the count of live WAL files (gauge). | no | +| `WalLiveSize` | wal_live_size is the size, in bytes, of live data in WAL files. With WAL recycling, this value is less than the actual on-disk size of the WAL files (gauge). | no | +| `WalObsoleteCount` | wal_obsolete_count is the count of obsolete WAL files (gauge). | no | +| `WalObsoleteSize` | wal_obsolete_size is the size of obsolete WAL files, in bytes (gauge). | no | +| `WalPhysicalSize` | wal_physical_size is the size, in bytes, of the WAL files on disk (gauge). | no | +| `WalBytesIn` | wal_bytes_in is the number of logical bytes written to the WAL (counter). | no | +| `WalBytesWritten` | wal_bytes_written is the number of bytes written to the WAL (counter). | no | +| `TableObsoleteCount` | table_obsolete_count is the number of tables which are no longer referenced by the current DB state or any open iterators (gauge). | no | +| `TableObsoleteSize` | table_obsolete_size is the size, in bytes, of obsolete tables (gauge). | no | +| `TableZombieCount` | table_zombie_count is the number of tables no longer referenced by the current DB state, but are still in use by an open iterator (gauge). | no | +| `TableZombieSize` | table_zombie_size is the size, in bytes, of zombie tables (gauge). | no | +| `RangeKeySetsCount` | range_key_sets_count is the approximate count of internal range key sets in the store. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `captured_index_usage_stats` + +An event of type `captured_index_usage_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `TotalReadCount` | TotalReadCount is the number of times the index has been read. | no | +| `LastRead` | LastRead is the timestamp at which the index was last read. | no | +| `TableID` | TableID is the ID of the table on which the index was created. This is same as descpb.TableID and is unique within the cluster. | no | +| `IndexID` | IndexID is the ID of the index within the scope of the given table. | no | +| `DatabaseName` | DatabaseName is the name of the database in which the index was created. | no | +| `TableName` | TableName is the name of the table on which the index was created. | no | +| `IndexName` | IndexName is the name of the index within the scope of the given table. | no | +| `IndexType` | IndexType is the type of the index. Index types include "primary" and "secondary". | no | +| `IsUnique` | IsUnique indicates if the index has a UNIQUE constraint. | no | +| `IsInverted` | IsInverted indicates if the index is an inverted index. | no | +| `CreatedAt` | CreatedAt is the timestamp at which the index was created. | no | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `changefeed_emitted_bytes` + +An event of type `changefeed_emitted_bytes` is an event representing the bytes emitted by a changefeed over an interval. + + +| Field | Description | Sensitive | +|--|--|--| +| `JobId` | The job id for enterprise changefeeds. | no | +| `EmittedBytes` | The number of bytes emitted. | no | +| `EmittedMessages` | The number of messages emitted. | no | +| `LoggingInterval` | The time period in nanoseconds between emitting telemetry events of this type (per-aggregator). | no | +| `Closing` | Flag to indicate that the changefeed is closing. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | + +### `changefeed_failed` + +An event of type `changefeed_failed` is an event for any Changefeed failure since the plan hook +was triggered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FailureType` | The reason / environment with which the changefeed failed (ex: connection_closed, changefeed_behind) | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | + +### `create_changefeed` + +An event of type `create_changefeed` is an event for any CREATE CHANGEFEED query that +successfully starts running. Failed CREATE statements will show up as +ChangefeedFailed events. + + +| Field | Description | Sensitive | +|--|--|--| +| `Transformation` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | + +### `hot_ranges_stats` + +An event of type `hot_ranges_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `Qps` | | no | +| `DatabaseName` | DatabaseName is the name of the database in which the index was created. | yes | +| `TableName` | TableName is the name of the table on which the index was created. | yes | +| `IndexName` | IndexName is the name of the index within the scope of the given table. | yes | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | yes | +| `LeaseholderNodeID` | LeaseholderNodeID indicates the Node ID that is the current leaseholder for the given range. | no | +| `WritesPerSecond` | Writes per second is the recent number of keys written per second on this range. | no | +| `ReadsPerSecond` | Reads per second is the recent number of keys read per second on this range. | no | +| `WriteBytesPerSecond` | Write bytes per second is the recent number of bytes written per second on this range. | no | +| `ReadBytesPerSecond` | Read bytes per second is the recent number of bytes read per second on this range. | no | +| `CPUTimePerSecond` | CPU time per second is the recent cpu usage in nanoseconds of this range. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `m_v_c_c_iterator_stats` + +Internal storage iteration statistics for a single execution. + + +| Field | Description | Sensitive | +|--|--|--| +| `StepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `StepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `BlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `BlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `KeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `ValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | + + + +### `recovery_event` + +An event of type `recovery_event` is an event that is logged on every invocation of BACKUP, +RESTORE, and on every BACKUP schedule creation, with the appropriate subset +of fields populated depending on the type of event. This event is is also +logged whenever a BACKUP and RESTORE job completes or fails. + + +| Field | Description | Sensitive | +|--|--|--| +| `RecoveryType` | RecoveryType is the type of recovery described by this event, which is one of - backup - scheduled_backup - create_schedule - restore

It can also be a job event corresponding to the recovery, which is one of - backup_job - scheduled_backup_job - restore_job | no | +| `TargetScope` | TargetScope is the largest scope of the targets that the user is backing up or restoring based on the following order: table < schema < database < full cluster. | no | +| `IsMultiregionTarget` | IsMultiregionTarget is true if any of the targets contain objects with multi-region primitives. | no | +| `TargetCount` | TargetCount is the number of targets the in the BACKUP/RESTORE. | no | +| `DestinationSubdirType` | DestinationSubdirType is - latest: if using the latest subdir - standard: if using a date-based subdir - custom: if using a custom subdir that's not date-based | no | +| `DestinationStorageTypes` | DestinationStorageTypes are the types of storage that the user is backing up to or restoring from. | no | +| `DestinationAuthTypes` | DestinationAuthTypes are the types of authentication methods that the user is using to access the destination storage. | no | +| `IsLocalityAware` | IsLocalityAware indicates if the BACKUP or RESTORE is locality aware. | no | +| `AsOfInterval` | AsOfInterval is the time interval in nanoseconds between the statement timestamp and the timestamp resolved by the AS OF SYSTEM TIME expression. The interval is expressed in nanoseconds. | no | +| `WithRevisionHistory` | WithRevisionHistory is true if the BACKUP includes revision history. | no | +| `HasEncryptionPassphrase` | HasEncryptionPassphrase is true if the user provided an encryption passphrase to encrypt/decrypt their backup. | no | +| `KMSType` | KMSType is the type of KMS the user is using to encrypt/decrypt their backup. | no | +| `KMSCount` | KMSCount is the number of KMS the user is using. | no | +| `Options` | Options contain all the names of the options specified by the user in the BACKUP or RESTORE statement. For options that are accompanied by a value, only those with non-empty values will be present.

It's important to note that there are no option values anywhere in the event payload. Future changes to telemetry should refrain from adding values to the payload unless they are properly redacted. | no | +| `DebugPauseOn` | DebugPauseOn is the type of event that the restore should pause on for debugging purposes. Currently only "error" is supported. | no | +| `JobID` | JobID is the ID of the BACKUP/RESTORE job. | no | +| `ResultStatus` | ResultStatus indicates whether the job succeeded or failed. | no | +| `ErrorText` | ErrorText is the text of the error that caused the job to fail. | partially | +| `RecurringCron` | RecurringCron is the crontab for the incremental backup. | no | +| `FullBackupCron` | FullBackupCron is the crontab for the full backup. | no | +| `CustomFirstRunTime` | CustomFirstRunTime is the timestamp for the user configured first run time. Expressed as nanoseconds since the Unix epoch. | no | +| `OnExecutionFailure` | OnExecutionFailure describes the desired behavior if the schedule fails to execute. | no | +| `OnPreviousRunning` | OnPreviousRunning describes the desired behavior if the previously scheduled BACKUP is still running. | no | +| `IgnoreExistingBackup` | IgnoreExistingBackup is true iff the BACKUP schedule should still be created even if a backup is already present in its destination. | no | +| `ApplicationName` | The application name for the session where recovery event was created. | no | +| `NumRows` | NumRows is the number of rows successfully imported, backed up or restored. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `sampled_exec_stats` + +An event of type `sampled_exec_stats` contains execution statistics that apply to both statements +and transactions. These stats as a whole are collected using a sampling approach. +These exec stats are meant to contain the same fields as ExecStats in +apps_stats.proto but are for a single execution rather than aggregated executions. +Fields in this struct should be updated in sync with apps_stats.proto. + + +| Field | Description | Sensitive | +|--|--|--| +| `NetworkBytes` | NetworkBytes collects the number of bytes sent over the network. | no | +| `MaxMemUsage` | MaxMemUsage collects the maximum memory usage that occurred on a node. | no | +| `ContentionTime` | ContentionTime collects the time in seconds statements in the transaction spent contending. | no | +| `NetworkMessages` | NetworkMessages collects the number of messages that were sent over the network. | no | +| `MaxDiskUsage` | MaxDiskUsage collects the maximum temporary disk usage that occurred. This is set in cases where a query had to spill to disk, e.g. when performing a large sort where not all of the tuples fit in memory. | no | +| `CPUSQLNanos` | CPUSQLNanos collects the CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `MVCCIteratorStats` | Internal storage iteration statistics. | yes | + + + +### `sampled_query` + +An event of type `sampled_query` is the SQL query event logged to the telemetry channel. It +contains common SQL event/execution details. + + +| Field | Description | Sensitive | +|--|--|--| +| `SkippedQueries` | skipped_queries indicate how many SQL statements were not considered for sampling prior to this one. If the field is omitted, or its value is zero, this indicates that no statement was omitted since the last event. | no | +| `CostEstimate` | Cost of the query as estimated by the optimizer. | no | +| `Distribution` | The distribution of the DistSQL query plan (local, full, or partial). | no | +| `PlanGist` | The query's plan gist bytes as a base64 encoded string. | no | +| `SessionID` | SessionID is the ID of the session that initiated the query. | no | +| `Database` | Name of the database that initiated the query. | no | +| `StatementID` | Statement ID of the query. | no | +| `TransactionID` | Transaction ID of the query. | no | +| `MaxFullScanRowsEstimate` | Maximum number of rows scanned by a full scan, as estimated by the optimizer. | no | +| `TotalScanRowsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer. | no | +| `OutputRowsEstimate` | The number of rows output by the query, as estimated by the optimizer. | no | +| `StatsAvailable` | Whether table statistics were available to the optimizer when planning the query. | no | +| `NanosSinceStatsCollected` | The maximum number of nanoseconds that have passed since stats were collected on any table scanned by this query. | no | +| `BytesRead` | The number of bytes read from disk. | no | +| `RowsRead` | The number of rows read from disk. | no | +| `RowsWritten` | The number of rows written. | no | +| `InnerJoinCount` | The number of inner joins in the query plan. | no | +| `LeftOuterJoinCount` | The number of left (or right) outer joins in the query plan. | no | +| `FullOuterJoinCount` | The number of full outer joins in the query plan. | no | +| `SemiJoinCount` | The number of semi joins in the query plan. | no | +| `AntiJoinCount` | The number of anti joins in the query plan. | no | +| `IntersectAllJoinCount` | The number of intersect all joins in the query plan. | no | +| `ExceptAllJoinCount` | The number of except all joins in the query plan. | no | +| `HashJoinCount` | The number of hash joins in the query plan. | no | +| `CrossJoinCount` | The number of cross joins in the query plan. | no | +| `IndexJoinCount` | The number of index joins in the query plan. | no | +| `LookupJoinCount` | The number of lookup joins in the query plan. | no | +| `MergeJoinCount` | The number of merge joins in the query plan. | no | +| `InvertedJoinCount` | The number of inverted joins in the query plan. | no | +| `ApplyJoinCount` | The number of apply joins in the query plan. | no | +| `ZigZagJoinCount` | The number of zig zag joins in the query plan. | no | +| `ContentionNanos` | The duration of time in nanoseconds that the query experienced contention. | no | +| `Regions` | The regions of the nodes where SQL processors ran. | no | +| `NetworkBytesSent` | The number of network bytes sent by nodes for this query. | no | +| `MaxMemUsage` | The maximum amount of memory usage by nodes for this query. | no | +| `MaxDiskUsage` | The maximum amount of disk usage by nodes for this query. | no | +| `KVBytesRead` | The number of bytes read at the KV layer for this query. | no | +| `KVPairsRead` | The number of key-value pairs read at the KV layer for this query. | no | +| `KVRowsRead` | The number of rows read at the KV layer for this query. | no | +| `NetworkMessages` | The number of network messages sent by nodes for this query. | no | +| `IndexRecommendations` | Generated index recommendations for this query. | no | +| `ScanCount` | The number of scans in the query plan. | no | +| `ScanWithStatsCount` | The number of scans using statistics (including forecasted statistics) in the query plan. | no | +| `ScanWithStatsForecastCount` | The number of scans using forecasted statistics in the query plan. | no | +| `TotalScanRowsWithoutForecastsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer without using forecasts. | no | +| `NanosSinceStatsForecasted` | The greatest quantity of nanoseconds that have passed since the forecast time (or until the forecast time, if it is in the future, in which case it will be negative) for any table with forecasted stats scanned by this query. | no | +| `Indexes` | The list of indexes used by this query. | no | +| `CpuTimeNanos` | Collects the cumulative CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `KvGrpcCalls` | The number of grpc calls done to get data form KV nodes | no | +| `KvTimeNanos` | Cumulated time spent waiting for a KV request. This includes disk IO time and potentially network time (if any of the keys are not local). | no | +| `ServiceLatencyNanos` | The time to service the query, from start of parse to end of execute. | no | +| `OverheadLatencyNanos` | The difference between service latency and the sum of parse latency + plan latency + run latency . | no | +| `RunLatencyNanos` | The time to run the query and fetch or compute the result rows. | no | +| `PlanLatencyNanos` | The time to transform the AST into a logical query plan. | no | +| `IdleLatencyNanos` | The time between statement executions in a transaction | no | +| `ParseLatencyNanos` | The time to transform the SQL string into an abstract syntax tree (AST). | no | +| `MvccStepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccStepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccBlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `MvccBlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `MvccKeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `SchemaChangerMode` | SchemaChangerMode is the mode that was used to execute the schema change, if any. | no | +| `SQLInstanceIDs` | SQLInstanceIDs is a list of all the SQL instances used in this statement's execution. | no | +| `StatementFingerprintID` | Statement fingerprint ID of the query. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sampled_transaction` + +An event of type `sampled_transaction` is the event logged to telemetry at the end of transaction execution. + + +| Field | Description | Sensitive | +|--|--|--| +| `User` | User is the user account that triggered the transaction. The special usernames `root` and `node` are not considered sensitive. | depends | +| `ApplicationName` | ApplicationName is the application name for the session where the transaction was executed. This is included in the event to ease filtering of logging output by application. | no | +| `TxnCounter` | TxnCounter is the sequence number of the SQL transaction inside its session. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `TransactionID` | TransactionID is the id of the transaction. | no | +| `Committed` | Committed indicates if the transaction committed successfully. We want to include this value even if it is false. | no | +| `ImplicitTxn` | ImplicitTxn indicates if the transaction was an implicit one. We want to include this value even if it is false. | no | +| `StartTimeUnixNanos` | StartTimeUnixNanos is the time the transaction was started. Expressed as unix time in nanoseconds. | no | +| `EndTimeUnixNanos` | EndTimeUnixNanos the time the transaction finished (either committed or aborted). Expressed as unix time in nanoseconds. | no | +| `ServiceLatNanos` | ServiceLatNanos is the time to service the whole transaction, from start to end of execution. | no | +| `SQLSTATE` | SQLSTATE is the SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | ErrorText is the text of the error if any. | partially | +| `NumRetries` | NumRetries is the number of time when the txn was retried automatically by the server. | no | +| `LastAutoRetryReason` | LastAutoRetryReason is a string containing the reason for the last automatic retry. | partially | +| `NumRows` | NumRows is the total number of rows returned across all statements. | no | +| `RetryLatNanos` | RetryLatNanos is the amount of time spent retrying the transaction. | no | +| `CommitLatNanos` | CommitLatNanos is the amount of time spent committing the transaction after all statement operations. | no | +| `IdleLatNanos` | IdleLatNanos is the amount of time spent waiting for the client to send statements while the transaction is open. | no | +| `BytesRead` | BytesRead is the number of bytes read from disk. | no | +| `RowsRead` | RowsRead is the number of rows read from disk. | no | +| `RowsWritten` | RowsWritten is the number of rows written to disk. | no | +| `SampledExecStats` | SampledExecStats is a nested field containing execution statistics. This field will be omitted if the stats were not sampled. | yes | +| `SkippedTransactions` | SkippedTransactions is the number of transactions that were skipped as part of sampling prior to this one. We only count skipped transactions when telemetry logging is enabled and the sampling mode is set to "transaction". | no | +| `TransactionFingerprintID` | TransactionFingerprintID is the fingerprint ID of the transaction. This can be used to find the transaction in the console. | no | +| `StatementFingerprintIDs` | StatementFingerprintIDs is an array of statement fingerprint IDs belonging to this transaction. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_descriptor` + +An event of type `schema_descriptor` is an event for schema telemetry, whose purpose is +to take periodic snapshots of the cluster's SQL schema and publish them in +the telemetry log channel. For all intents and purposes, the data in such a +snapshot can be thought of the outer join of certain system tables: +namespace, descriptor, and at some point perhaps zones, etc. + +Snapshots are too large to conveniently be published as a single log event, +so instead they're broken down into SchemaDescriptor events which +contain the data in one record of this outer join projection. These events +are prefixed by a header (a SchemaSnapshotMetadata event). + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of the snapshot that this event is part of. | no | +| `ParentDatabaseID` | ParentDatabaseID matches the same key column in system.namespace. | no | +| `ParentSchemaID` | ParentSchemaID matches the same key column in system.namespace. | no | +| `Name` | Name matches the same key column in system.namespace. | no | +| `DescID` | DescID matches the 'id' column in system.namespace and system.descriptor. | no | +| `Desc` | Desc matches the 'descriptor' column in system.descriptor. Some contents of the descriptor may be redacted to prevent leaking PII. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_snapshot_metadata` + +An event of type `schema_snapshot_metadata` is an event describing a schema snapshot, which +is a set of SchemaDescriptor messages sharing the same SnapshotID. + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of this snapshot. | no | +| `NumRecords` | NumRecords is how many SchemaDescriptor events are in the snapshot. | no | +| `AsOfTimestamp` | AsOfTimestamp is when the snapshot was taken. This is equivalent to the timestamp given in the AS OF SYSTEM TIME clause when querying the namespace and descriptor tables in the system database. Expressed as nanoseconds since the Unix epoch. | no | +| `Errors` | Errors records any errors encountered when post-processing this snapshot, which includes the redaction of any potential PII. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Zone config events + +Events in this category pertain to zone configuration changes on +the SQL schema or system ranges. + +When zone configs apply to individual tables or other objects in a +SQL logical schema, they are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these zone config events are preserved +in each tenant's own `system.eventlog` table. + +When they apply to cluster-level ranges (e.g., the system zone config), +they are stored in the system tenant's own `system.eventlog` table. + +Events in this category are logged to the `OPS` channel. + + +### `remove_zone_config` + +An event of type `remove_zone_config` is recorded when a zone config is removed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `set_zone_config` + +An event of type `set_zone_config` is recorded when a zone config is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `ResolvedOldConfig` | The string representation of the resolved old zone config. This is not necessarily the same as the zone config that was previously set -- as it includes the resolved values of the zone config options. In other words, a zone config that hasn't been properly "set" yet (and inherits from its parent) will have a resolved_old_config that has details of the values it inherits from its parent. This is particularly useful to get a proper diff between the old and new zone config. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + + + + +## Enumeration types + +### `AuthFailReason` + +AuthFailReason is the inventory of possible reasons for an +authentication failure. + + +| Value | Textual alias in code or documentation | Description | +|--|--|--| +| 0 | UNKNOWN | is reported when the reason is unknown. | +| 1 | USER_RETRIEVAL_ERROR | occurs when there was an internal error accessing the principals. | +| 2 | USER_NOT_FOUND | occurs when the principal is unknown. | +| 3 | LOGIN_DISABLED | occurs when the user does not have LOGIN privileges. | +| 4 | METHOD_NOT_FOUND | occurs when no HBA rule matches or the method does not exist. | +| 5 | PRE_HOOK_ERROR | occurs when the authentication handshake encountered a protocol error. | +| 6 | CREDENTIALS_INVALID | occurs when the client-provided credentials were invalid. | +| 7 | CREDENTIALS_EXPIRED | occur when the credentials provided by the client are expired. | +| 8 | NO_REPLICATION_ROLEOPTION | occurs when the connection requires a replication role option, but the user does not have it. | + + + diff --git a/src/current/_includes/cockroach-generated/release-24.1/logformats.md b/src/current/_includes/cockroach-generated/release-24.1/logformats.md new file mode 100644 index 00000000000..89580c9fc15 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.1/logformats.md @@ -0,0 +1,382 @@ + +The supported log output formats are documented below. + + +- [`crdb-v1`](#format-crdb-v1) + +- [`crdb-v1-count`](#format-crdb-v1-count) + +- [`crdb-v1-tty`](#format-crdb-v1-tty) + +- [`crdb-v1-tty-count`](#format-crdb-v1-tty-count) + +- [`crdb-v2`](#format-crdb-v2) + +- [`crdb-v2-tty`](#format-crdb-v2-tty) + +- [`json`](#format-json) + +- [`json-compact`](#format-json-compact) + +- [`json-fluent`](#format-json-fluent) + +- [`json-fluent-compact`](#format-json-fluent-compact) + + + +## Format `crdb-v1` + + +This is a legacy file format used from CockroachDB v1.0. + +Each log entry is emitted using a common prefix, described below, followed by: + +- The logging context tags enclosed between `[` and `]`, if any. It is possible + for this to be omitted if there were no context tags. +- Optionally, a counter column, if the option 'show-counter' is enabled. See below for details. +- the text of the log entry. + +Beware that the text of the log entry can span multiple lines. +The following caveats apply: + +- The text of the log entry can start with text enclosed between `[` and `]`. + If there were no logging tags to start with, it is not possible to distinguish between + logging context tag information and a `[...]` string in the main text of the + log entry. This means that this format is ambiguous. + + To remove this ambiguity, you can use the option 'show-counter'. + +- The text of the log entry can embed arbitrary application-level strings, + including strings that represent log entries. In particular, an accident + of implementation can cause the common entry prefix (described below) + to also appear on a line of its own, as part of the payload of a previous + log entry. There is no automated way to recognize when this occurs. + Care must be taken by a human observer to recognize these situations. + +- The log entry parser provided by CockroachDB to read log files is faulty + and is unable to recognize the aforementioned pitfall; nor can it read + entries larger than 64KiB successfully. Generally, use of this internal + log entry parser is discouraged for entries written with this format. + +See the newer format `crdb-v2` for an alternative +without these limitations. + +### Header lines + +At the beginning of each file, a header is printed using a similar format as +regular log entries. This header reports when the file was created, +which parameters were used to start the server, the server identifiers +if known, and other metadata about the running process. + +- This header appears to be logged at severity `INFO` (with an `I` prefix + at the start of the line) even though it does not really have a severity. +- The header is printed unconditionally even when a filter is configured to + omit entries at the `INFO` level. + +### Common log entry prefix + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker tags counter + +Reminder, the tags may be omitted; and the counter is only printed if the option +'show-counter' is specified. + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (omitted if zero for use by tests). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. | +| line | The line number where the entry originated. | +| marker | Redactability marker ` + redactableIndicator + ` (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. May be absent. | +| counter | The entry counter. Only included if 'show-counter' is enabled. | + +The redactability marker can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. + +If the marker ` + redactableIndicator + ` is present, the remainder of the log entry +contains delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `show-counter` | Whether to include the counter column in the line header. Without it, the format may be ambiguous due to the optionality of tags. | +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v1-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: none` + + +## Format `crdb-v1-tty` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: false` +- `colors: auto` + + +## Format `crdb-v1-tty-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: auto` + + +## Format `crdb-v2` + +This is the main file format used from CockroachDB v21.1. + +Each log entry is emitted using a common prefix, described below, +followed by the text of the log entry. + +### Entry format + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker [tags...] counter cont + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (zero when cannot be determined). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. Also see below. | +| line | The line number where the entry originated. | +| marker | Redactability marker "⋮" (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. See below. | +| counter | The optional entry counter (see below for details). | +| cont | Continuation mark for structured and multi-line entries. See below. | + +The `chan@` prefix before the file name indicates the logging channel, +and is omitted if the channel is `DEV`. + +The file name may be prefixed by the string `(gostd) ` to indicate +that the log entry was produced inside the Go standard library, instead +of a CockroachDB component. Entry parsers must be configured to ignore this prefix +when present. + +`marker` can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. +If the marker "⋮" is present, the remainder of the log entry +contains delimiters (‹...›) +around fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +when log redaction is requested. + +The logging `tags` are enclosed between square brackets `[...]`, +and the syntax `[-]` is used when there are no logging tags +associated with the log entry. + +`counter` is numeric, and is incremented for every +log entry emitted to this sink. (There is thus one counter sequence per +sink.) For entries that do not have a counter value +associated (e.g., header entries in file sinks), the counter position +in the common prefix is empty: `tags` is then +followed by two ASCII space characters, instead of one space; the `counter`, +and another space. The presence of the two ASCII spaces indicates +reliably that no counter was present. + +`cont` is a format/continuation indicator: + +| Continuation indicator | ASCII | Description | +|------------------------|-------|--| +| space | 0x32 | Start of an unstructured entry. | +| equal sign, "=" | 0x3d | Start of a structured entry. | +| exclamation mark, "!" | 0x21 | Start of an embedded stack trace. | +| plus sign, "+" | 0x2b | Continuation of a multi-line entry. The payload contains a newline character at this position. | +| vertical bar | 0x7c | Continuation of a large entry. | + +### Examples + +Example single-line unstructured entry: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 started with engine type ‹2› +~~~ + +Example multi-line unstructured entry: + +~~~ +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 node startup completed: +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 +CockroachDB node starting at 2021-01-16 21:49 (took 0.0s) +~~~ + +Example structured entry: + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventType":"node_restart"} +~~~ + +Example long entries broken up into multiple lines: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.... +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 |aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +~~~ + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventTy... +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 |pe":"node_restart"} +~~~ + +### Backward-compatibility notes + +Entries in this format can be read by most `crdb-v1` log parsers, +in particular the one included in the DB console and +also the [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +facility. + +However, implementers of previous version parsers must +understand that the logging tags field is now always +included, and the lack of logging tags is included +by a tag string set to `[-]`. + +Likewise, the entry counter is now also always included, +and there is a special character after `counter` +to indicate whether the remainder of the line is a +structured entry, or a continuation of a previous entry. + +Finally, in the previous format, structured entries +were prefixed with the string `Structured entry: `. In +the new format, they are prefixed by the `=` continuation +indicator. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v2-tty` + +This format name is an alias for 'crdb-v2' with +the following format option defaults: + +- `colors: auto` + + +## Format `json` + +This format emits log entries as a JSON payload. + +The JSON object is guaranteed to not contain unescaped newlines +or other special characters, and the entry as a whole is followed +by a newline character. This makes the format suitable for +processing over a stream unambiguously. + +Each entry contains at least the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `tag` | `tag` | (Only if the option `fluent-tag: true` is given.) A Fluent tag for the event, formed by the process name and the logging channel. | +| `d` | `datetime` | The pretty-printed date/time of the event timestamp, if enabled via options. | +| `f` | `file` | The name of the source file where the event was emitted. | +| `g` | `goroutine` | The identifier of the goroutine where the event was emitted. | +| `l` | `line` | The line number where the event was emitted in the source. | +| `r` | `redactable` | Whether the payload is redactable (see below for details). | +| `t` | `timestamp` | The timestamp at which the event was emitted on the logging channel. | +| `v` | `version` | The binary version with which the event was generated. | + + +After a couple of *header* entries written at the beginning of each log sink, +all subsequent log entries also contain the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `C` | `channel` | The name of the logging channel where the event was sent. | +| `sev` | `severity` | The severity of the event. | +| `c` | `channel_numeric` | The numeric identifier for the logging channel where the event was sent. | +| `n` | `entry_counter` | The entry number on this logging sink, relative to the last process restart. | +| `s` | `severity_numeric` | The numeric value of the severity of the event. | + + +Additionally, the following fields are conditionally present: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `N` | `node_id` | The node ID where the event was generated, once known. Only reported for single-tenant or KV servers. | +| `x` | `cluster_id` | The cluster ID where the event was generated, once known. Only reported for single-tenant of KV servers. | +| `q` | `instance_id` | The SQL instance ID where the event was generated, once known. | +| `T` | `tenant_id` | The SQL tenant ID where the event was generated, once known. | +| `V` | `tenant_name` | The SQL virtual cluster where the event was generated, once known. | +| `tags` | `tags` | The logging context tags for the entry, if there were context tags. | +| `message` | `message` | For unstructured events, the flat text payload. | +| `event` | `event` | The logging event, if structured (see below for details). | +| `stacks` | `stacks` | Goroutine stacks, for fatal events. | + +When an entry is structured, the `event` field maps to a dictionary +whose structure is one of the documented structured events. See the [reference documentation](eventlog.html) +for structured events for a list of possible payloads. + +When the entry is marked as `redactable`, the `tags`, `message`, and/or `event` payloads +contain delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `datetime-format` | The format to use for the `datetime` field. The value can be one of `none`, `iso8601`/`rfc3339` (synonyms), or `rfc1123`. Default is `none`. | +| `datetime-timezone` | The timezone to use for the `datetime` field. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | +| `tag-style` | The tags to include in the envelope. The value can be `compact` (one letter tags) or `verbose` (long-form tags). Default is `verbose`. | +| `fluent-tag` | Whether to produce an additional field called `tag` for Fluent compatibility. Default is `false`. | + + + +## Format `json-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: false` +- `tag-style: compact` + + +## Format `json-fluent` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: verbose` + + +## Format `json-fluent-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: compact` + + diff --git a/src/current/_includes/cockroach-generated/release-24.1/logging.md b/src/current/_includes/cockroach-generated/release-24.1/logging.md new file mode 100644 index 00000000000..8b628dc2dd9 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.1/logging.md @@ -0,0 +1,179 @@ +## Logging levels (severities) + +### INFO + +The `INFO` severity is used for informational messages that do not +require action. + +### WARNING + +The `WARNING` severity is used for situations which may require special handling, +where normal operation is expected to resume automatically. + +### ERROR + +The `ERROR` severity is used for situations that require special handling, +where normal operation could not proceed as expected. +Other operations can continue mostly unaffected. + +### FATAL + +The `FATAL` severity is used for situations that require an immedate, hard +server shutdown. A report is also sent to telemetry if telemetry +is enabled. + + +## Logging channels + +### `DEV` + +The `DEV` channel is used during development to collect log +details useful for troubleshooting that fall outside the +scope of other channels. It is also the default logging +channel for events not associated with a channel. + +This channel is special in that there are no constraints as to +what may or may not be logged on it. Conversely, users in +production deployments are invited to not collect `DEV` logs in +centralized logging facilities, because they likely contain +sensitive operational data. +See [Configure logs](configure-logs.html#dev-channel). + +### `OPS` + +The `OPS` channel is used to report "point" operational events, +initiated by user operators or automation: + + - Operator or system actions on server processes: process starts, + stops, shutdowns, crashes (if they can be logged), + including each time: command-line parameters, current version being run + - Actions that impact the topology of a cluster: node additions, + removals, decommissions, etc. + - Job-related initiation or termination + - [Cluster setting](cluster-settings.html) changes + - [Zone configuration](configure-replication-zones.html) changes + +### `HEALTH` + +The `HEALTH` channel is used to report "background" operational +events, initiated by CockroachDB or reporting on automatic processes: + + - Current resource usage, including critical resource usage + - Node-node connection events, including connection errors and + gossip details + - Range and table leasing events + - Up- and down-replication, range unavailability + +### `STORAGE` + +The `STORAGE` channel is used to report low-level storage +layer events (RocksDB/Pebble). + +### `SESSIONS` + +The `SESSIONS` channel is used to report client network activity when enabled via +the `server.auth_log.sql_connections.enabled` and/or +`server.auth_log.sql_sessions.enabled` [cluster setting](cluster-settings.html): + + - Connections opened/closed + - Authentication events: logins, failed attempts + - Session and query cancellation + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_SCHEMA` + +The `SQL_SCHEMA` channel is used to report changes to the +SQL logical schema, excluding privilege and ownership changes +(which are reported separately on the `PRIVILEGES` channel) and +zone configuration changes (which go to the `OPS` channel). + +This includes: + + - Database/schema/table/sequence/view/type creation + - Adding/removing/changing table columns + - Changing sequence parameters + +`SQL_SCHEMA` events generally comprise changes to the schema that affect the +functional behavior of client apps using stored objects. + +### `USER_ADMIN` + +The `USER_ADMIN` channel is used to report changes +in users and roles, including: + + - Users added/dropped + - Changes to authentication credentials (e.g., passwords, validity, etc.) + - Role grants/revocations + - Role option grants/revocations + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `PRIVILEGES` + +The `PRIVILEGES` channel is used to report data +authorization changes, including: + + - Privilege grants/revocations on database, objects, etc. + - Object ownership changes + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SENSITIVE_ACCESS` + +The `SENSITIVE_ACCESS` channel is used to report SQL +data access to sensitive data: + + - Data access audit events (when table audit is enabled via + [ALTER TABLE ... EXPERIMENTAL_AUDIT](alter-table.html#experimental_audit)) + - Data access audit events (when role-based audit is enabled via + [`sql.log.user_audit` cluster setting](role-based-audit-logging.html#syntax-of-audit-settings)) + - SQL statements executed by users with the admin role + - Operations that write to system tables + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_EXEC` + +The `SQL_EXEC` channel is used to report SQL execution on +behalf of client connections: + + - Logical SQL statement executions (when enabled via the + `sql.log.all_statements.enabled` [cluster setting](cluster-settings.html)) + - uncaught Go panic errors during the execution of a SQL statement. + +### `SQL_PERF` + +The `SQL_PERF` channel is used to report SQL executions +that are marked as "out of the ordinary" +to facilitate performance investigations. +This includes the SQL "slow query log". + +Arguably, this channel overlaps with `SQL_EXEC`. +However, we keep both channels separate for backward compatibility +with versions prior to v21.1, where the corresponding events +were redirected to separate files. + +### `SQL_INTERNAL_PERF` + +The `SQL_INTERNAL_PERF` channel is like the `SQL_PERF` channel, but is aimed at +helping developers of CockroachDB itself. It exists as a separate +channel so as to not pollute the `SQL_PERF` logging output with +internal troubleshooting details. + +### `TELEMETRY` + +The `TELEMETRY` channel reports telemetry events. Telemetry events describe +feature usage within CockroachDB and anonymizes any application- +specific data. + +### `KV_DISTRIBUTION` + +The `KV_DISTRIBUTION` channel is used to report data distribution events, such as moving +replicas between stores in the cluster, or adding (removing) replicas to +ranges. + diff --git a/src/current/_includes/cockroach-generated/release-24.1/settings/settings.html b/src/current/_includes/cockroach-generated/release-24.1/settings/settings.html new file mode 100644 index 00000000000..be6ebf12087 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.1/settings/settings.html @@ -0,0 +1,310 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingTypeDefaultDescriptionSupported Deployments
admission.disk_bandwidth_tokens.elastic.enabled
booleantruewhen true, and provisioned bandwidth for the disk corresponding to a store is configured, tokens for elastic work will be limited if disk bandwidth becomes a bottleneckDedicated/Self-Hosted
admission.epoch_lifo.enabled
booleanfalsewhen true, epoch-LIFO behavior is enabled when there is significant delay in admissionServerless/Dedicated/Self-Hosted
admission.epoch_lifo.epoch_closing_delta_duration
duration5msthe delta duration before closing an epoch, for epoch-LIFO admission control orderingServerless/Dedicated/Self-Hosted
admission.epoch_lifo.epoch_duration
duration100msthe duration of an epoch, for epoch-LIFO admission control orderingServerless/Dedicated/Self-Hosted
admission.epoch_lifo.queue_delay_threshold_to_switch_to_lifo
duration105msthe queue delay encountered by a (tenant,priority) for switching to epoch-LIFO orderingServerless/Dedicated/Self-Hosted
admission.kv.enabled
booleantruewhen true, work performed by the KV layer is subject to admission controlDedicated/Self-Hosted
admission.sql_kv_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a KV response is subject to admission controlServerless/Dedicated/Self-Hosted
admission.sql_sql_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a DistSQL response is subject to admission controlServerless/Dedicated/Self-Hosted
bulkio.backup.deprecated_full_backup_with_subdir.enabled
booleanfalsewhen true, a backup command with a user specified subdirectory will create a full backup at the subdirectory if no backup already exists at that subdirectoryServerless/Dedicated/Self-Hosted
bulkio.backup.file_size
byte size128 MiBtarget size for individual data files produced during BACKUPServerless/Dedicated/Self-Hosted
bulkio.backup.read_timeout
duration5m0samount of time after which a read attempt is considered timed out, which causes the backup to failServerless/Dedicated/Self-Hosted
bulkio.backup.read_with_priority_after
duration1m0samount of time since the read-as-of time above which a BACKUP should use priority when retrying readsServerless/Dedicated/Self-Hosted
physical_replication.consumer.minimum_flush_interval
(alias: bulkio.stream_ingestion.minimum_flush_interval)
duration5sthe minimum timestamp between flushes; flushes may still occur if internal buffers fill upDedicated/Self-Hosted
changefeed.aggregator.flush_jitter
float0.1jitter aggregator flushes as a fraction of min_checkpoint_frequency. This setting has no effect if min_checkpoint_frequency is set to 0.Serverless/Dedicated/Self-Hosted
changefeed.backfill.concurrent_scan_requests
integer0number of concurrent scan requests per node issued during a backfillServerless/Dedicated/Self-Hosted
changefeed.backfill.scan_request_size
integer524288the maximum number of bytes returned by each scan requestServerless/Dedicated/Self-Hosted
changefeed.batch_reduction_retry.enabled
(alias: changefeed.batch_reduction_retry_enabled)
booleanfalseif true, kafka changefeeds upon erroring on an oversized batch will attempt to resend the messages with progressively lower batch sizesServerless/Dedicated/Self-Hosted
changefeed.default_range_distribution_strategy
enumerationdefaultconfigures how work is distributed among nodes for a given changefeed. for the most balanced distribution, use `balanced_simple`. changing this setting will not override locality restrictions [default = 0, balanced_simple = 1]Serverless/Dedicated/Self-Hosted
changefeed.event_consumer_worker_queue_size
integer16if changefeed.event_consumer_workers is enabled, this setting sets the maxmimum number of events which a worker can bufferServerless/Dedicated/Self-Hosted
changefeed.event_consumer_workers
integer0the number of workers to use when processing events: <0 disables, 0 assigns a reasonable default, >0 assigns the setting value. for experimental/core changefeeds and changefeeds using parquet format, this is disabledServerless/Dedicated/Self-Hosted
changefeed.fast_gzip.enabled
booleantrueuse fast gzip implementationServerless/Dedicated/Self-Hosted
changefeed.frontier_highwater_lag_checkpoint_threshold
duration10m0scontrols the maximum the high-water mark is allowed to lag behind the leading spans of the frontier before per-span checkpointing is enabled; if 0, checkpointing due to high-water lag is disabledServerless/Dedicated/Self-Hosted
changefeed.kafka_v2_error_details.enabled
booleanfalseif enabled, Kafka v2 sinks will include the message key, size, and MVCC timestamp in message too large errorsServerless/Dedicated/Self-Hosted
changefeed.memory.per_changefeed_limit
byte size512 MiBcontrols amount of data that can be buffered per changefeedServerless/Dedicated/Self-Hosted
changefeed.min_highwater_advance
duration0sminimum amount of time the changefeed high water mark must advance for it to be eligible for checkpointing; Default of 0 will checkpoint every time frontier advances, as long as the rate of checkpointing keeps up with the rate of frontier changesServerless/Dedicated/Self-Hosted
changefeed.node_throttle_config
stringspecifies node level throttling configuration for all changefeeedsServerless/Dedicated/Self-Hosted
changefeed.protect_timestamp.max_age
duration96h0m0sfail the changefeed if the protected timestamp age exceeds this threshold; 0 disables expirationServerless/Dedicated/Self-Hosted
changefeed.protect_timestamp_interval
duration10m0scontrols how often the changefeed forwards its protected timestamp to the resolved timestampServerless/Dedicated/Self-Hosted
changefeed.schema_feed.read_with_priority_after
duration1m0sretry with high priority if we were not able to read descriptors for too long; 0 disablesServerless/Dedicated/Self-Hosted
changefeed.sink_io_workers
integer0the number of workers used by changefeeds when sending requests to the sink (currently the batching versions of webhook, pubsub, and kafka sinks that are enabled by changefeed.new_<sink type>_sink_enabled only): <0 disables, 0 assigns a reasonable default, >0 assigns the setting valueServerless/Dedicated/Self-Hosted
cloudstorage.azure.concurrent_upload_buffers
integer1controls the number of concurrent buffers that will be used by the Azure client when uploading chunks.Each buffer can buffer up to cloudstorage.write_chunk.size of memory during an uploadServerless/Dedicated/Self-Hosted
cloudstorage.http.custom_ca
stringcustom root CA (appended to system's default CAs) for verifying certificates when interacting with HTTPS storageServerless/Dedicated/Self-Hosted
cloudstorage.timeout
duration10m0sthe timeout for import/export storage operationsServerless/Dedicated/Self-Hosted
cluster.auto_upgrade.enabled
booleantruedisable automatic cluster version upgrade until resetServerless/Dedicated/Self-Hosted
cluster.organization
stringorganization nameServerless/Dedicated/Self-Hosted (read-only)
cluster.preserve_downgrade_option
stringdisable (automatic or manual) cluster version upgrade from the specified version until resetServerless/Dedicated/Self-Hosted
diagnostics.active_query_dumps.enabled
booleantrueexperimental: enable dumping of anonymized active queries to disk when node is under memory pressureServerless/Dedicated/Self-Hosted (read-only)
diagnostics.forced_sql_stat_reset.interval
duration2h0m0sinterval after which the reported SQL Stats are reset even if not collected by telemetry reporter. It has a max value of 24H.Serverless/Dedicated/Self-Hosted
diagnostics.memory_monitoring_dumps.enabled
booleantrueenable dumping of memory monitoring state at the same time as heap profiles are takenServerless/Dedicated/Self-Hosted (read-only)
diagnostics.reporting.enabled
booleantrueenable reporting diagnostic metrics to cockroach labs, but is ignored for Trial or Free licensesServerless/Dedicated/Self-Hosted
diagnostics.reporting.interval
duration1h0m0sinterval at which diagnostics data should be reportedServerless/Dedicated/Self-Hosted
enterprise.license
stringthe encoded cluster licenseServerless/Dedicated/Self-Hosted (read-only)
external.graphite.endpoint
stringif nonempty, push server metrics to the Graphite or Carbon server at the specified host:portServerless/Dedicated/Self-Hosted
external.graphite.interval
duration10sthe interval at which metrics are pushed to Graphite (if enabled)Serverless/Dedicated/Self-Hosted
feature.backup.enabled
booleantrueset to true to enable backups, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.changefeed.enabled
booleantrueset to true to enable changefeeds, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.export.enabled
booleantrueset to true to enable exports, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.import.enabled
booleantrueset to true to enable imports, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.restore.enabled
booleantrueset to true to enable restore, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.schema_change.enabled
booleantrueset to true to enable schema changes, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.stats.enabled
booleantrueset to true to enable CREATE STATISTICS/ANALYZE, false to disable; default is trueServerless/Dedicated/Self-Hosted
jobs.retention_time
duration336h0m0sthe amount of time for which records for completed jobs are retainedServerless/Dedicated/Self-Hosted
kv.allocator.lease_rebalance_threshold
float0.05minimum fraction away from the mean a store's lease count can be before it is considered for lease-transfersDedicated/Self-Hosted
kv.allocator.load_based_lease_rebalancing.enabled
booleantrueset to enable rebalancing of range leases based on load and latencyDedicated/Self-Hosted
kv.allocator.load_based_rebalancing
enumerationleases and replicaswhether to rebalance based on the distribution of load across stores [off = 0, leases = 1, leases and replicas = 2]Dedicated/Self-Hosted
kv.allocator.load_based_rebalancing.objective
enumerationcpuwhat objective does the cluster use to rebalance; if set to `qps` the cluster will attempt to balance qps among stores, if set to `cpu` the cluster will attempt to balance cpu usage among stores [qps = 0, cpu = 1]Dedicated/Self-Hosted
kv.allocator.load_based_rebalancing_interval
duration1m0sthe rough interval at which each store will check for load-based lease / replica rebalancing opportunitiesDedicated/Self-Hosted
kv.allocator.qps_rebalance_threshold
float0.1minimum fraction away from the mean a store's QPS (such as queries per second) can be before it is considered overfull or underfullDedicated/Self-Hosted
kv.allocator.range_rebalance_threshold
float0.05minimum fraction away from the mean a store's range count can be before it is considered overfull or underfullDedicated/Self-Hosted
kv.allocator.store_cpu_rebalance_threshold
float0.1minimum fraction away from the mean a store's cpu usage can be before it is considered overfull or underfullDedicated/Self-Hosted
kv.bulk_io_write.max_rate
byte size1.0 TiBthe rate limit (bytes/sec) to use for writes to disk on behalf of bulk io opsDedicated/Self-Hosted
kv.bulk_sst.max_allowed_overage
byte size64 MiBif positive, allowed size in excess of target size for SSTs from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryDedicated/Self-Hosted
kv.bulk_sst.target_size
byte size16 MiBtarget size for SSTs emitted from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryServerless/Dedicated/Self-Hosted (read-only)
kv.closed_timestamp.follower_reads.enabled
(alias: kv.closed_timestamp.follower_reads_enabled)
booleantrueallow (all) replicas to serve consistent historical reads based on closed timestamp informationServerless/Dedicated/Self-Hosted (read-only)
kv.closed_timestamp.lead_for_global_reads_override
duration0sif nonzero, overrides the lead time that global_read ranges use to publish closed timestampsServerless/Dedicated/Self-Hosted (read-only)
kv.closed_timestamp.side_transport_interval
duration200msthe interval at which the closed timestamp side-transport attempts to advance each range's closed timestamp; set to 0 to disable the side-transportServerless/Dedicated/Self-Hosted (read-only)
kv.closed_timestamp.target_duration
duration3sif nonzero, attempt to provide closed timestamp notifications for timestamps trailing cluster time by approximately this durationServerless/Dedicated/Self-Hosted (read-only)
kv.dist_sender.circuit_breaker.cancellation.enabled
booleantruewhen enabled, in-flight requests will be cancelled when the circuit breaker tripsServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.cancellation.write_grace_period
duration10show long after the circuit breaker trips to cancel write requests (these can't retry internally, so should be long enough to allow quorum/lease recovery)Serverless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.probe.interval
duration3sinterval between replica probesServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.probe.threshold
duration3sduration of errors or stalls after which a replica will be probedServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.probe.timeout
duration3stimeout for replica probesServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breakers.mode
enumerationliveness range onlyset of ranges to trip circuit breakers for failing or stalled replicas [no ranges = 0, liveness range only = 1, all ranges = 2]Serverless/Dedicated/Self-Hosted
kv.lease_transfer_read_summary.global_budget
byte size0 Bcontrols the maximum number of bytes that will be used to summarize the global segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Dedicated/Self-Hosted
kv.lease_transfer_read_summary.local_budget
byte size4.0 MiBcontrols the maximum number of bytes that will be used to summarize the local segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Dedicated/Self-Hosted
kv.log_range_and_node_events.enabled
booleantrueset to true to transactionally log range events (e.g., split, merge, add/remove voter/non-voter) into system.rangelogand node join and restart events into system.eventologDedicated/Self-Hosted
kv.protectedts.reconciliation.interval
duration5m0sthe frequency for reconciling jobs with protected timestamp recordsServerless/Dedicated/Self-Hosted (read-only)
kv.range_split.by_load.enabled
(alias: kv.range_split.by_load_enabled)
booleantrueallow automatic splits of ranges based on where load is concentratedDedicated/Self-Hosted
kv.range_split.load_cpu_threshold
duration500msthe CPU use per second over which, the range becomes a candidate for load based splittingDedicated/Self-Hosted
kv.range_split.load_qps_threshold
integer2500the QPS over which, the range becomes a candidate for load based splittingDedicated/Self-Hosted
kv.rangefeed.client.stream_startup_rate
integer100controls the rate per second the client will initiate new rangefeed stream for a single range; 0 implies unlimitedServerless/Dedicated/Self-Hosted
kv.rangefeed.closed_timestamp_refresh_interval
duration3sthe interval at which closed-timestamp updatesare delivered to rangefeeds; set to 0 to use kv.closed_timestamp.side_transport_intervalServerless/Dedicated/Self-Hosted (read-only)
kv.rangefeed.enabled
booleanfalseif set, rangefeed registration is enabledServerless/Dedicated/Self-Hosted (read-only)
kv.rangefeed.range_stuck_threshold
duration1m0srestart rangefeeds if they don't emit anything for the specified threshold; 0 disables (kv.rangefeed.closed_timestamp_refresh_interval takes precedence)Serverless/Dedicated/Self-Hosted
kv.replica_circuit_breaker.slow_replication_threshold
duration1m0sduration after which slow proposals trip the per-Replica circuit breaker (zero duration disables breakers)Dedicated/Self-Hosted
kv.replica_stats.addsst_request_size_factor
integer50000the divisor that is applied to addsstable request sizes, then recorded in a leaseholders QPS; 0 means all requests are treated as cost 1Dedicated/Self-Hosted
kv.replication_reports.interval
duration1m0sthe frequency for generating the replication_constraint_stats, replication_stats_report and replication_critical_localities reports (set to 0 to disable)Dedicated/Self-Hosted
kv.snapshot_rebalance.max_rate
byte size32 MiBthe rate limit (bytes/sec) to use for rebalance and upreplication snapshotsDedicated/Self-Hosted
kv.snapshot_receiver.excise.enabled
booleantrueset to false to disable excises in place of range deletions for KV snapshotsDedicated/Self-Hosted
kv.transaction.max_intents_bytes
integer4194304maximum number of bytes used to track locks in transactionsServerless/Dedicated/Self-Hosted
kv.transaction.max_refresh_spans_bytes
integer4194304maximum number of bytes used to track refresh spans in serializable transactionsServerless/Dedicated/Self-Hosted
kv.transaction.reject_over_max_intents_budget.enabled
booleanfalseif set, transactions that exceed their lock tracking budget (kv.transaction.max_intents_bytes) are rejected instead of having their lock spans imprecisely compressedServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.locking_reads.enabled
booleantrueif enabled, transactional locking reads are pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.ranged_writes.enabled
booleantrueif enabled, transactional ranged writes are pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.enabled
(alias: kv.transaction.write_pipelining_enabled)
booleantrueif enabled, transactional writes are pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.max_batch_size
(alias: kv.transaction.write_pipelining_max_batch_size)
integer128if non-zero, defines that maximum size batch that will be pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kvadmission.store.provisioned_bandwidth
byte size0 Bif set to a non-zero value, this is used as the provisioned bandwidth (in bytes/s), for each store. It can be overridden on a per-store basis using the --store flag. Note that setting the provisioned bandwidth to a positive value may enable disk bandwidth based admission control, since admission.disk_bandwidth_tokens.elastic.enabled defaults to trueDedicated/Self-Hosted
schedules.backup.gc_protection.enabled
booleantrueenable chaining of GC protection across backups run as part of a scheduleServerless/Dedicated/Self-Hosted
security.client_cert.subject_required.enabled
booleanfalsemandates a requirement for subject role to be set for db userServerless/Dedicated/Self-Hosted (read-only)
security.ocsp.mode
enumerationoffuse OCSP to check whether TLS certificates are revoked. If the OCSP server is unreachable, in strict mode all certificates will be rejected and in lax mode all certificates will be accepted. [off = 0, lax = 1, strict = 2]Serverless/Dedicated/Self-Hosted
security.ocsp.timeout
duration3stimeout before considering the OCSP server unreachableServerless/Dedicated/Self-Hosted
server.auth_log.sql_connections.enabled
booleanfalseif set, log SQL client connect and disconnect events to the SESSIONS log channel (note: may hinder performance on loaded nodes)Serverless/Dedicated/Self-Hosted
server.auth_log.sql_sessions.enabled
booleanfalseif set, log verbose SQL session authentication events to the SESSIONS log channel (note: may hinder performance on loaded nodes). Session start and end events are always logged regardless of this setting; disable the SESSIONS log channel to suppress them.Serverless/Dedicated/Self-Hosted
server.authentication_cache.enabled
booleantrueenables a cache used during authentication to avoid lookups to system tables when retrieving per-user authentication-related informationServerless/Dedicated/Self-Hosted
server.child_metrics.enabled
booleanfalseenables the exporting of child metrics, additional prometheus time series with extra labelsServerless/Dedicated/Self-Hosted
server.client_cert_expiration_cache.capacity
integer1000the maximum number of client cert expirations storedServerless/Dedicated/Self-Hosted
server.clock.forward_jump_check.enabled
(alias: server.clock.forward_jump_check_enabled)
booleanfalseif enabled, forward clock jumps > max_offset/2 will cause a panicServerless/Dedicated/Self-Hosted
server.clock.persist_upper_bound_interval
duration0sthe interval between persisting the wall time upper bound of the clock. The clock does not generate a wall time greater than the persisted timestamp and will panic if it sees a wall time greater than this value. When cockroach starts, it waits for the wall time to catch-up till this persisted timestamp. This guarantees monotonic wall time across server restarts. Not setting this or setting a value of 0 disables this feature.Serverless/Dedicated/Self-Hosted
server.consistency_check.max_rate
byte size8.0 MiBthe rate limit (bytes/sec) to use for consistency checks; used in conjunction with server.consistency_check.interval to control the frequency of consistency checks. Note that setting this too high can negatively impact performance.Dedicated/Self-Hosted
server.eventlog.enabled
booleantrueif set, logged notable events are also stored in the table system.eventlogServerless/Dedicated/Self-Hosted
server.eventlog.ttl
duration2160h0m0sif nonzero, entries in system.eventlog older than this duration are periodically purgedServerless/Dedicated/Self-Hosted
server.host_based_authentication.configuration
stringhost-based authentication configuration to use during connection authenticationServerless/Dedicated/Self-Hosted
server.hot_ranges_request.node.timeout
duration5m0sthe duration allowed for a single node to return hot range data before the request is cancelled; if set to 0, there is no timeoutServerless/Dedicated/Self-Hosted
server.hsts.enabled
booleanfalseif true, HSTS headers will be sent along with all HTTP requests. The headers will contain a max-age setting of one year. Browsers honoring the header will always use HTTPS to access the DB Console. Ensure that TLS is correctly configured prior to enabling.Serverless/Dedicated/Self-Hosted
server.http.base_path
string/path to redirect the user to upon succcessful loginServerless/Dedicated/Self-Hosted
server.identity_map.configuration
stringsystem-identity to database-username mappingsServerless/Dedicated/Self-Hosted
server.log_gc.max_deletions_per_cycle
integer1000the maximum number of entries to delete on each purge of log-like system tablesServerless/Dedicated/Self-Hosted
server.log_gc.period
duration1h0m0sthe period at which log-like system tables are checked for old entriesServerless/Dedicated/Self-Hosted
server.max_connections_per_gateway
integer-1the maximum number of SQL connections per gateway allowed at a given time (note: this will only limit future connection attempts and will not affect already established connections). Negative values result in unlimited number of connections. Superusers are not affected by this limit.Serverless/Dedicated/Self-Hosted
server.max_open_transactions_per_gateway
integer-1the maximum number of open SQL transactions per gateway allowed at a given time. Negative values result in unlimited number of connections. Superusers are not affected by this limit.Serverless/Dedicated/Self-Hosted
server.oidc_authentication.autologin.enabled
(alias: server.oidc_authentication.autologin)
booleanfalseif true, logged-out visitors to the DB Console will be automatically redirected to the OIDC login endpointServerless/Dedicated/Self-Hosted
server.oidc_authentication.button_text
stringLog in with your OIDC providertext to show on button on DB Console login page to login with your OIDC provider (only shown if OIDC is enabled)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.claim_json_key
stringsets JSON key of principal to extract from payload after OIDC authentication completes (usually email or sid)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.client_id
stringsets OIDC client idServerless/Dedicated/Self-Hosted
server.oidc_authentication.client_secret
stringsets OIDC client secretServerless/Dedicated/Self-Hosted
server.oidc_authentication.enabled
booleanfalseenables or disabled OIDC login for the DB ConsoleServerless/Dedicated/Self-Hosted
server.oidc_authentication.principal_regex
string(.+)regular expression to apply to extracted principal (see claim_json_key setting) to translate to SQL user (golang regex format, must include 1 grouping to extract)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.provider_url
stringsets OIDC provider URL ({provider_url}/.well-known/openid-configuration must resolve)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.redirect_url
stringhttps://localhost:8080/oidc/v1/callbacksets OIDC redirect URL via a URL string or a JSON string containing a required `redirect_urls` key with an object that maps from region keys to URL strings (URLs should point to your load balancer and must route to the path /oidc/v1/callback)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.scopes
stringopenidsets OIDC scopes to include with authentication request (space delimited list of strings, required to start with `openid`)Serverless/Dedicated/Self-Hosted
server.rangelog.ttl
duration720h0m0sif nonzero, entries in system.rangelog older than this duration are periodically purgedDedicated/Self-Hosted
server.redact_sensitive_settings.enabled
booleanfalseenables or disables the redaction of sensitive settings in the output of SHOW CLUSTER SETTINGS and SHOW ALL CLUSTER SETTINGS for users without the MODIFYCLUSTERSETTING privilegeServerless/Dedicated/Self-Hosted
server.shutdown.connections.timeout
(alias: server.shutdown.connection_wait)
duration0sthe maximum amount of time a server waits for all SQL connections to be closed before proceeding with a drain. (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Serverless/Dedicated/Self-Hosted
server.shutdown.initial_wait
(alias: server.shutdown.drain_wait)
duration0sthe amount of time a server waits in an unready state before proceeding with a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting. --drain-wait is to specify the duration of the whole draining process, while server.shutdown.initial_wait is to set the wait time for health probes to notice that the node is not ready.)Serverless/Dedicated/Self-Hosted
server.shutdown.lease_transfer_iteration.timeout
(alias: server.shutdown.lease_transfer_wait)
duration5sthe timeout for a single iteration of the range lease transfer phase of draining (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Dedicated/Self-Hosted
server.shutdown.transactions.timeout
(alias: server.shutdown.query_wait)
duration10sthe timeout for waiting for active transactions to finish during a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Serverless/Dedicated/Self-Hosted
server.sql_tcp_keep_alive.count
integer3maximum number of probes that will be sent out before a connection is dropped because it's unresponsive (Linux and Darwin only)Serverless/Dedicated/Self-Hosted
server.sql_tcp_keep_alive.interval
duration10stime between keep alive probes and idle time before probes are sent outServerless/Dedicated/Self-Hosted
server.time_until_store_dead
duration5m0sthe time after which if there is no new gossiped information about a store, it is considered deadServerless/Dedicated/Self-Hosted
server.user_login.cert_password_method.auto_scram_promotion.enabled
booleantruewhether to automatically promote cert-password authentication to use SCRAMServerless/Dedicated/Self-Hosted
server.user_login.downgrade_scram_stored_passwords_to_bcrypt.enabled
booleantrueif server.user_login.password_encryption=crdb-bcrypt, this controls whether to automatically re-encode stored passwords using scram-sha-256 to crdb-bcryptServerless/Dedicated/Self-Hosted
server.user_login.min_password_length
integer1the minimum length accepted for passwords set in cleartext via SQL. Note that a value lower than 1 is ignored: passwords cannot be empty in any case.Serverless/Dedicated/Self-Hosted
server.user_login.password_encryption
enumerationscram-sha-256which hash method to use to encode cleartext passwords passed via ALTER/CREATE USER/ROLE WITH PASSWORD [crdb-bcrypt = 2, scram-sha-256 = 3]Serverless/Dedicated/Self-Hosted
server.user_login.password_hashes.default_cost.crdb_bcrypt
integer10the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method crdb-bcrypt (allowed range: 4-31)Serverless/Dedicated/Self-Hosted
server.user_login.password_hashes.default_cost.scram_sha_256
integer10610the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method scram-sha-256 (allowed range: 4096-240000000000)Serverless/Dedicated/Self-Hosted
server.user_login.rehash_scram_stored_passwords_on_cost_change.enabled
booleantrueif server.user_login.password_hashes.default_cost.scram_sha_256 differs from, the cost in a stored hash, this controls whether to automatically re-encode stored passwords using scram-sha-256 with the new default costServerless/Dedicated/Self-Hosted
server.user_login.timeout
duration10stimeout after which client authentication times out if some system range is unavailable (0 = no timeout)Serverless/Dedicated/Self-Hosted
server.user_login.upgrade_bcrypt_stored_passwords_to_scram.enabled
booleantrueif server.user_login.password_encryption=scram-sha-256, this controls whether to automatically re-encode stored passwords using crdb-bcrypt to scram-sha-256Serverless/Dedicated/Self-Hosted
server.web_session.purge.ttl
duration1h0m0sif nonzero, entries in system.web_sessions older than this duration are periodically purgedServerless/Dedicated/Self-Hosted
server.web_session.timeout
(alias: server.web_session_timeout)
duration168h0m0sthe duration that a newly created web session will be validServerless/Dedicated/Self-Hosted
spanconfig.bounds.enabled
booleantruedictates whether span config bounds are consulted when serving span configs for secondary tenantsDedicated/Self-Hosted
spanconfig.range_coalescing.system.enabled
(alias: spanconfig.storage_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs, for the ranges specific to the system tenantDedicated/Self-Hosted
spanconfig.range_coalescing.application.enabled
(alias: spanconfig.tenant_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs across all secondary tenant keyspacesDedicated/Self-Hosted
sql.auth.change_own_password.enabled
booleanfalsecontrols whether a user is allowed to change their own password, even if they have no other privilegesServerless/Dedicated/Self-Hosted
sql.auth.grant_option_for_owner.enabled
booleantruedetermines whether the GRANT OPTION for privileges is implicitly given to the owner of an objectServerless/Dedicated/Self-Hosted
sql.auth.grant_option_inheritance.enabled
booleantruedetermines whether the GRANT OPTION for privileges is inherited through role membershipServerless/Dedicated/Self-Hosted
sql.auth.public_schema_create_privilege.enabled
booleantruedetermines whether to grant all users the CREATE privileges on the public schema when it is createdServerless/Dedicated/Self-Hosted
sql.closed_session_cache.capacity
integer1000the maximum number of sessions in the cacheServerless/Dedicated/Self-Hosted
sql.closed_session_cache.time_to_live
integer3600the maximum time to live, in secondsServerless/Dedicated/Self-Hosted
sql.contention.event_store.capacity
byte size64 MiBthe in-memory storage capacity per-node of contention event storeServerless/Dedicated/Self-Hosted
sql.contention.event_store.duration_threshold
duration0sminimum contention duration to cause the contention events to be collected into crdb_internal.transaction_contention_eventsServerless/Dedicated/Self-Hosted
sql.contention.record_serialization_conflicts.enabled
booleantrueenables recording 40001 errors with conflicting txn meta as SERIALIZATION_CONFLICTcontention events into crdb_internal.transaction_contention_eventsServerless/Dedicated/Self-Hosted
sql.contention.txn_id_cache.max_size
byte size64 MiBthe maximum byte size TxnID cache will use (set to 0 to disable)Serverless/Dedicated/Self-Hosted
sql.cross_db_fks.enabled
booleanfalseif true, creating foreign key references across databases is allowedServerless/Dedicated/Self-Hosted
sql.cross_db_sequence_owners.enabled
booleanfalseif true, creating sequences owned by tables from other databases is allowedServerless/Dedicated/Self-Hosted
sql.cross_db_sequence_references.enabled
booleanfalseif true, sequences referenced by tables from other databases are allowedServerless/Dedicated/Self-Hosted
sql.cross_db_views.enabled
booleanfalseif true, creating views that refer to other databases is allowedServerless/Dedicated/Self-Hosted
sql.defaults.cost_scans_with_default_col_size.enabled
booleanfalsesetting to true uses the same size for all columns to compute scan cost
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.datestyle
enumerationiso, mdydefault value for DateStyle session setting [iso, mdy = 0, iso, dmy = 1, iso, ymd = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.default_hash_sharded_index_bucket_count
integer16used as bucket count if bucket count is not specified in hash sharded index definition
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.default_int_size
integer8the size, in bytes, of an INT type
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.disallow_full_table_scans.enabled
booleanfalsesetting to true rejects queries that have planned a full table scan
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.distsql
enumerationautodefault distributed SQL execution mode [off = 0, auto = 1, on = 2, always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_alter_column_type.enabled
booleanfalsedefault value for experimental_alter_column_type session setting; enables the use of ALTER COLUMN TYPE for general conversions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_distsql_planning
enumerationoffdefault experimental_distsql_planning mode; enables experimental opt-driven DistSQL planning [off = 0, on = 1]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_enable_unique_without_index_constraints.enabled
booleanfalsedefault value for experimental_enable_unique_without_index_constraints session setting;disables unique without index constraints by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_implicit_column_partitioning.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for the use of implicit column partitioning
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_temporary_tables.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for use of temporary tables by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.foreign_key_cascades_limit
integer10000default value for foreign_key_cascades_limit session setting; limits the number of cascading operations that run as part of a single query
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.idle_in_session_timeout
duration0sdefault value for the idle_in_session_timeout; default value for the idle_in_session_timeout session setting; controls the duration a session is permitted to idle before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.idle_in_transaction_session_timeout
duration0sdefault value for the idle_in_transaction_session_timeout; controls the duration a session is permitted to idle in a transaction before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.implicit_select_for_update.enabled
booleantruedefault value for enable_implicit_select_for_update session setting; enables FOR UPDATE locking during the row-fetch phase of mutation statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.insert_fast_path.enabled
booleantruedefault value for enable_insert_fast_path session setting; enables a specialized insert path
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.intervalstyle
enumerationpostgresdefault value for IntervalStyle session setting [postgres = 0, iso_8601 = 1, sql_standard = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.large_full_scan_rows
float1000default value for large_full_scan_rows session setting which determines the maximum table size allowed for a full scan when disallow_full_table_scans is set to true
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.locality_optimized_partitioned_index_scan.enabled
booleantruedefault value for locality_optimized_partitioned_index_scan session setting; enables searching for rows in the current region before searching remote regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.lock_timeout
duration0sdefault value for the lock_timeout; default value for the lock_timeout session setting; controls the duration a query is permitted to wait while attempting to acquire a lock on a key or while blocking on an existing lock in order to perform a non-locking read on a key; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.on_update_rehome_row.enabled
booleantruedefault value for on_update_rehome_row; enables ON UPDATE rehome_row() expressions to trigger on updates
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.optimizer_use_histograms.enabled
booleantruedefault value for optimizer_use_histograms session setting; enables usage of histograms in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.optimizer_use_multicol_stats.enabled
booleantruedefault value for optimizer_use_multicol_stats session setting; enables usage of multi-column stats in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.override_alter_primary_region_in_super_region.enabled
booleanfalsedefault value for override_alter_primary_region_in_super_region; allows for altering the primary region even if the primary region is a member of a super region
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.override_multi_region_zone_config.enabled
booleanfalsedefault value for override_multi_region_zone_config; allows for overriding the zone configs of a multi-region table or database
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.prefer_lookup_joins_for_fks.enabled
booleanfalsedefault value for prefer_lookup_joins_for_fks session setting; causes foreign key operations to use lookup joins when possible
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.primary_region
stringif not empty, all databases created without a PRIMARY REGION will implicitly have the given PRIMARY REGION
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.reorder_joins_limit
integer8default number of joins to reorder
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.require_explicit_primary_keys.enabled
booleanfalsedefault value for requiring explicit primary keys in CREATE TABLE statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.results_buffer.size
byte size512 KiBdefault size of the buffer that accumulates results for a statement or a batch of statements before they are sent to the client. This can be overridden on an individual connection with the 'results_buffer_size' parameter. Note that auto-retries generally only happen while no results have been delivered to the client, so reducing this size can increase the number of retriable errors a client receives. On the other hand, increasing the buffer size can increase the delay until the client receives the first result row. Updating the setting only affects new connections. Setting to 0 disables any buffering.
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.serial_normalization
enumerationrowiddefault handling of SERIAL in table definitions [rowid = 0, virtual_sequence = 1, sql_sequence = 2, sql_sequence_cached = 3, unordered_rowid = 4, sql_sequence_cached_node = 5]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.statement_timeout
duration0sdefault value for the statement_timeout; default value for the statement_timeout session setting; controls the duration a query is permitted to run before it is canceled; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.stub_catalog_tables.enabled
booleantruedefault value for stub_catalog_tables session setting
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.super_regions.enabled
booleanfalsedefault value for enable_super_regions; allows for the usage of super regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_read_err
integer0the limit for the number of rows read by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_read_log
integer0the threshold for the number of rows read by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_written_err
integer0the limit for the number of rows written by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_written_log
integer0the threshold for the number of rows written by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.use_declarative_schema_changer
enumerationondefault value for use_declarative_schema_changer session setting;disables new schema changer by default [off = 0, on = 1, unsafe = 2, unsafe_always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.vectorize
enumerationondefault vectorize mode [on = 0, on = 2, experimental_always = 3, off = 4]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.zigzag_join.enabled
booleanfalsedefault value for enable_zigzag_join session setting; disallows use of zig-zag join by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.distsql.temp_storage.workmem
byte size64 MiBmaximum amount of memory in bytes a processor can use before falling back to temp storageServerless/Dedicated/Self-Hosted
sql.guardrails.max_row_size_err
byte size512 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an error is returned; use 0 to disableServerless/Dedicated/Self-Hosted
sql.guardrails.max_row_size_log
byte size64 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an event is logged to SQL_PERF (or SQL_INTERNAL_PERF if the mutating statement was internal); use 0 to disableServerless/Dedicated/Self-Hosted
sql.hash_sharded_range_pre_split.max
integer16max pre-split ranges to have when adding hash sharded index to an existing tableServerless/Dedicated/Self-Hosted
sql.index_recommendation.drop_unused_duration
duration168h0m0sthe index unused duration at which we begin to recommend dropping the indexServerless/Dedicated/Self-Hosted
sql.insights.anomaly_detection.enabled
booleantrueenable per-fingerprint latency recording and anomaly detectionServerless/Dedicated/Self-Hosted
sql.insights.anomaly_detection.latency_threshold
duration50msstatements must surpass this threshold to trigger anomaly detection and identificationServerless/Dedicated/Self-Hosted
sql.insights.anomaly_detection.memory_limit
byte size1.0 MiBthe maximum amount of memory allowed for tracking statement latenciesServerless/Dedicated/Self-Hosted
sql.insights.execution_insights_capacity
integer1000the size of the per-node store of execution insightsServerless/Dedicated/Self-Hosted
sql.insights.high_retry_count.threshold
integer10the number of retries a slow statement must have undergone for its high retry count to be highlighted as a potential problemServerless/Dedicated/Self-Hosted
sql.insights.latency_threshold
duration100msamount of time after which an executing statement is considered slow. Use 0 to disable.Serverless/Dedicated/Self-Hosted
sql.log.slow_query.experimental_full_table_scans.enabled
booleanfalsewhen set to true, statements that perform a full table/index scan will be logged to the slow query log even if they do not meet the latency threshold. Must have the slow query log enabled for this setting to have any effect.Serverless/Dedicated/Self-Hosted
sql.log.slow_query.internal_queries.enabled
booleanfalsewhen set to true, internal queries which exceed the slow query log threshold are logged to a separate log. Must have the slow query log enabled for this setting to have any effect.Serverless/Dedicated/Self-Hosted
sql.log.slow_query.latency_threshold
duration0swhen set to non-zero, log statements whose service latency exceeds the threshold to a secondary logger on each nodeServerless/Dedicated/Self-Hosted
sql.log.user_audit
stringuser/role-based audit logging configuration. An enterprise license is required for this cluster setting to take effect.Serverless/Dedicated/Self-Hosted
sql.log.user_audit.reduced_config.enabled
booleanfalseenables logic to compute a reduced audit configuration, computing the audit configuration only once at session start instead of at each SQL event. The tradeoff with the increase in performance (~5%), is that changes to the audit configuration (user role memberships/cluster setting) are not reflected within session. Users will need to start a new session to see these changes in their auditing behaviour.Serverless/Dedicated/Self-Hosted
sql.metrics.index_usage_stats.enabled
booleantruecollect per index usage statisticsServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_reported_stmt_fingerprints
integer100000the maximum number of reported statement fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_reported_txn_fingerprints
integer100000the maximum number of reported transaction fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_stmt_fingerprints
integer7500the maximum number of statement fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_txn_fingerprints
integer7500the maximum number of transaction fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.dump_to_logs.enabled
(alias: sql.metrics.statement_details.dump_to_logs)
booleanfalsedump collected statement statistics to node logs when periodically clearedServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.enabled
booleantruecollect per-statement query statisticsServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.gateway_node.enabled
booleanfalsesave the gateway node for each statement fingerprint. If false, the value will be stored as 0.Serverless/Dedicated/Self-Hosted
sql.metrics.statement_details.index_recommendation_collection.enabled
booleantruegenerate an index recommendation for each fingerprint IDServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.max_mem_reported_idx_recommendations
integer5000the maximum number of reported index recommendation info stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.plan_collection.enabled
booleanfalseperiodically save a logical plan for each fingerprintServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.plan_collection.period
duration5m0sthe time until a new logical plan is collectedServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.threshold
duration0sminimum execution time to cause statement statistics to be collected. If configured, no transaction stats are collected.Serverless/Dedicated/Self-Hosted
sql.metrics.transaction_details.enabled
booleantruecollect per-application transaction statisticsServerless/Dedicated/Self-Hosted
sql.multiple_modifications_of_table.enabled
booleanfalseif true, allow statements containing multiple INSERT ON CONFLICT, UPSERT, UPDATE, or DELETE subqueries modifying the same table, at the risk of data corruption if the same row is modified multiple times by a single statement (multiple INSERT subqueries without ON CONFLICT cannot cause corruption and are always allowed)Serverless/Dedicated/Self-Hosted
sql.multiregion.drop_primary_region.enabled
booleantrueallows dropping the PRIMARY REGION of a database if it is the last regionServerless/Dedicated/Self-Hosted
sql.notices.enabled
booleantrueenable notices in the server/client protocol being sentServerless/Dedicated/Self-Hosted
sql.optimizer.uniqueness_checks_for_gen_random_uuid.enabled
booleanfalseif enabled, uniqueness checks may be planned for mutations of UUID columns updated with gen_random_uuid(); otherwise, uniqueness is assumed due to near-zero collision probabilityServerless/Dedicated/Self-Hosted
sql.schema.telemetry.recurrence
string@weeklycron-tab recurrence for SQL schema telemetry jobServerless/Dedicated/Self-Hosted (read-only)
sql.spatial.experimental_box2d_comparison_operators.enabled
booleanfalseenables the use of certain experimental box2d comparison operatorsServerless/Dedicated/Self-Hosted
sql.stats.activity.persisted_rows.max
integer200000maximum number of rows of statement and transaction activity that will be persisted in the system tablesServerless/Dedicated/Self-Hosted
sql.stats.automatic_collection.enabled
booleantrueautomatic statistics collection modeServerless/Dedicated/Self-Hosted
sql.stats.automatic_collection.fraction_stale_rows
float0.2target fraction of stale rows per table that will trigger a statistics refreshServerless/Dedicated/Self-Hosted
sql.stats.automatic_collection.min_stale_rows
integer500target minimum number of stale rows per table that will trigger a statistics refreshServerless/Dedicated/Self-Hosted
sql.stats.cleanup.recurrence
string@hourlycron-tab recurrence for SQL Stats cleanup jobServerless/Dedicated/Self-Hosted
sql.stats.flush.enabled
booleantrueif set, SQL execution statistics are periodically flushed to diskServerless/Dedicated/Self-Hosted
sql.stats.flush.interval
duration10m0sthe interval at which SQL execution statistics are flushed to disk, this value must be less than or equal to 1 hourServerless/Dedicated/Self-Hosted
sql.stats.forecasts.enabled
booleantruewhen true, enables generation of statistics forecasts by default for all tablesServerless/Dedicated/Self-Hosted
sql.stats.forecasts.max_decrease
float0.3333333333333333the most a prediction is allowed to decrease, expressed as the minimum ratio of the prediction to the lowest prior observationServerless/Dedicated/Self-Hosted
sql.stats.forecasts.min_goodness_of_fit
float0.95the minimum R² (goodness of fit) measurement required from all predictive models to use a forecastServerless/Dedicated/Self-Hosted
sql.stats.forecasts.min_observations
integer3the mimimum number of observed statistics required to produce a statistics forecastServerless/Dedicated/Self-Hosted
sql.stats.histogram_buckets.count
integer200maximum number of histogram buckets to build during table statistics collectionServerless/Dedicated/Self-Hosted
sql.stats.histogram_collection.enabled
booleantruehistogram collection modeServerless/Dedicated/Self-Hosted
sql.stats.histogram_samples.count
integer10000number of rows sampled for histogram construction during table statistics collectionServerless/Dedicated/Self-Hosted
sql.stats.multi_column_collection.enabled
booleantruemulti-column statistics collection modeServerless/Dedicated/Self-Hosted
sql.stats.non_default_columns.min_retention_period
duration24h0m0sminimum retention period for table statistics collected on non-default columnsServerless/Dedicated/Self-Hosted
sql.stats.non_indexed_json_histograms.enabled
booleantrueset to true to collect table statistics histograms on non-indexed JSON columnsServerless/Dedicated/Self-Hosted
sql.stats.persisted_rows.max
integer1000000maximum number of rows of statement and transaction statistics that will be persisted in the system tables before compaction beginsServerless/Dedicated/Self-Hosted
sql.stats.post_events.enabled
booleanfalseif set, an event is logged for every CREATE STATISTICS jobServerless/Dedicated/Self-Hosted
sql.stats.response.max
integer20000the maximum number of statements and transaction stats returned in a CombinedStatements requestServerless/Dedicated/Self-Hosted
sql.stats.response.show_internal.enabled
booleanfalsecontrols if statistics for internal executions should be returned by the CombinedStatements and if internal sessions should be returned by the ListSessions endpoints. These endpoints are used to display statistics on the SQL Activity pagesServerless/Dedicated/Self-Hosted
sql.stats.system_tables.enabled
booleantruewhen true, enables use of statistics on system tables by the query optimizerServerless/Dedicated/Self-Hosted
sql.stats.system_tables_autostats.enabled
booleantruewhen true, enables automatic collection of statistics on system tablesServerless/Dedicated/Self-Hosted
sql.stats.virtual_computed_columns.enabled
booleantrueset to true to collect table statistics on virtual computed columnsServerless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.enabled
booleanfalsewhen set to true, executed queries will emit an event on the telemetry logging channelServerless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.internal.enabled
booleanfalsewhen set to true, internal queries will be sampled in telemetry loggingServerless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample executions for telemetry, note that it is recommended that this value shares a log-line limit of 10 logs per second on the telemetry pipeline with all other telemetry events. If sampling mode is set to 'transaction', this value is ignored.Serverless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.mode
enumerationstatementthe execution level used for telemetry sampling. If set to 'statement', events are sampled at the statement execution level. If set to 'transaction', events are sampled at the transaction execution level, i.e. all statements for a transaction will be logged and are counted together as one sampled event (events are still emitted one per statement). [statement = 0, transaction = 1]Serverless/Dedicated/Self-Hosted
sql.telemetry.transaction_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample transactions for telemetry. If sampling mode is set to 'statement', this setting is ignored. In practice, this means that we only sample a transaction if 1/max_event_frequency seconds have elapsed since the last transaction was sampled.Serverless/Dedicated/Self-Hosted
sql.telemetry.transaction_sampling.statement_events_per_transaction.max
integer50the maximum number of statement events to log for every sampled transaction. Note that statements that are logged by force do not adhere to this limit.Serverless/Dedicated/Self-Hosted
sql.temp_object_cleaner.cleanup_interval
duration30m0show often to clean up orphaned temporary objectsServerless/Dedicated/Self-Hosted
sql.temp_object_cleaner.wait_interval
duration30m0show long after creation a temporary object will be cleaned upServerless/Dedicated/Self-Hosted
sql.log.all_statements.enabled
(alias: sql.trace.log_statement_execute)
booleanfalseset to true to enable logging of all executed statementsServerless/Dedicated/Self-Hosted
sql.trace.stmt.enable_threshold
duration0senables tracing on all statements; statements executing for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting applies to individual statements within a transaction and is therefore finer-grained than sql.trace.txn.enable_thresholdServerless/Dedicated/Self-Hosted
sql.trace.txn.enable_threshold
duration0senables tracing on all transactions; transactions open for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting is coarser-grained than sql.trace.stmt.enable_threshold because it applies to all statements within a transaction as well as client communication (e.g. retries)Serverless/Dedicated/Self-Hosted
sql.ttl.changefeed_replication.disabled
booleanfalseif true, deletes issued by TTL will not be replicated via changefeeds (this setting will be ignored by changefeeds that have the ignore_disable_changefeed_replication option set; such changefeeds will continue to replicate all TTL deletes)Serverless/Dedicated/Self-Hosted
sql.ttl.default_delete_batch_size
integer100default amount of rows to delete in a single query during a TTL jobServerless/Dedicated/Self-Hosted
sql.ttl.default_delete_rate_limit
integer100default delete rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Serverless/Dedicated/Self-Hosted
sql.ttl.default_select_batch_size
integer500default amount of rows to select in a single query during a TTL jobServerless/Dedicated/Self-Hosted
sql.ttl.default_select_rate_limit
integer0default select rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Serverless/Dedicated/Self-Hosted
sql.ttl.job.enabled
booleantruewhether the TTL job is enabledServerless/Dedicated/Self-Hosted
sql.txn.read_committed_isolation.enabled
booleantrueset to true to allow transactions to use the READ COMMITTED isolation level if specified by BEGIN/SET commandsServerless/Dedicated/Self-Hosted
sql.txn_fingerprint_id_cache.capacity
integer100the maximum number of txn fingerprint IDs storedServerless/Dedicated/Self-Hosted
storage.experimental.eventually_file_only_snapshots.enabled
booleantrueset to false to disable eventually-file-only-snapshots (kv.snapshot_receiver.excise.enabled must also be false)Dedicated/Self-Hosted
storage.ingest_split.enabled
booleantrueset to false to disable ingest-time splitting that lowers write-amplificationDedicated/Self-Hosted
storage.max_sync_duration
duration20smaximum duration for disk operations; any operations that take longer than this setting trigger a warning log entry or process crashServerless/Dedicated/Self-Hosted (read-only)
storage.max_sync_duration.fatal.enabled
booleantrueif true, fatal the process when a disk operation exceeds storage.max_sync_durationServerless/Dedicated/Self-Hosted
storage.sstable.compression_algorithm
enumerationsnappydetermines the compression algorithm to use when compressing sstable data blocks; supported values: "snappy", "zstd" [snappy = 1, zstd = 2]Serverless/Dedicated/Self-Hosted (read-only)
storage.value_blocks.enabled
booleantrueset to true to enable writing of value blocks in sstablesServerless/Dedicated/Self-Hosted
storage.wal_failover.unhealthy_op_threshold
duration100msthe latency of a WAL write considered unhealthy and triggers a failover to a secondary WAL locationDedicated/Self-Hosted
timeseries.storage.enabled
booleantrueif set, periodic timeseries data is stored within the cluster; disabling is not recommended unless you are storing the data elsewhereDedicated/Self-Hosted
timeseries.storage.resolution_10s.ttl
duration240h0m0sthe maximum age of time series data stored at the 10 second resolution. Data older than this is subject to rollup and deletion.Serverless/Dedicated/Self-Hosted (read-only)
timeseries.storage.resolution_30m.ttl
duration2160h0m0sthe maximum age of time series data stored at the 30 minute resolution. Data older than this is subject to deletion.Serverless/Dedicated/Self-Hosted (read-only)
trace.debug_http_endpoint.enabled
(alias: trace.debug.enable)
booleanfalseif set, traces for recent requests can be seen at https://<ui>/debug/requestsServerless/Dedicated/Self-Hosted
trace.opentelemetry.collector
stringaddress of an OpenTelemetry trace collector to receive traces using the otel gRPC protocol, as <host>:<port>. If no port is specified, 4317 will be used.Serverless/Dedicated/Self-Hosted
trace.snapshot.rate
duration0sif non-zero, interval at which background trace snapshots are capturedServerless/Dedicated/Self-Hosted
trace.span_registry.enabled
booleantrueif set, ongoing traces can be seen at https://<ui>/#/debug/tracezServerless/Dedicated/Self-Hosted
trace.zipkin.collector
stringthe address of a Zipkin instance to receive traces, as <host>:<port>. If no port is specified, 9411 will be used.Serverless/Dedicated/Self-Hosted
ui.database_locality_metadata.enabled
booleantrueif enabled shows extended locality data about databases and tables in DB Console which can be expensive to computeServerless/Dedicated/Self-Hosted
ui.display_timezone
enumerationetc/utcthe timezone used to format timestamps in the ui [etc/utc = 0, america/new_york = 1]Serverless/Dedicated/Self-Hosted
version
version24.1set the active cluster version in the format '<major>.<minor>'Serverless/Dedicated/Self-Hosted
diff --git a/src/current/_includes/cockroach-generated/release-24.1/sql/aggregates.md b/src/current/_includes/cockroach-generated/release-24.1/sql/aggregates.md new file mode 100644 index 00000000000..3213f0f02a8 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.1/sql/aggregates.md @@ -0,0 +1,579 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_agg(arg1: bool) → bool[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bool[]) → bool[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes) → bytes[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes[]) → bytes[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date) → date[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date[]) → date[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal) → decimal[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal[]) → decimal[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float) → float[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float[]) → float[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet) → inet[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet[]) → inet[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int) → int[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int[]) → int[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval) → interval[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval[]) → interval[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string) → string[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string[]) → string[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time) → time[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time[]) → time[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp) → timestamp[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp[]) → timestamp[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz) → timestamptz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz[]) → timestamptz[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid) → uuid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid[]) → uuid[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum) → anyenum[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum[]) → anyenum[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d) → box2d[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d[]) → box2d[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography) → geography[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography[]) → geography[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry) → geometry[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry[]) → geometry[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb) → jsonb[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb[]) → jsonb[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid) → oid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid[]) → oid[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn) → pg_lsn[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn[]) → pg_lsn[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor) → refcursor[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor[]) → refcursor[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz) → timetz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz[]) → timetz[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple) → tuple[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple[]) → tuple[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit) → varbit[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit[]) → varbit[][]

Aggregates the selected values into an array.

+		Immutable
array_cat_agg(arg1: bool[]) → bool[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: bytes[]) → bytes[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: date[]) → date[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: decimal[]) → decimal[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: float[]) → float[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: inet[]) → inet[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: int[]) → int[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: interval[]) → interval[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: string[]) → string[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: time[]) → time[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamp[]) → timestamp[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamptz[]) → timestamptz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: uuid[]) → uuid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: anyenum[]) → anyenum[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: box2d[]) → box2d[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geography[]) → geography[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geometry[]) → geometry[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: jsonb[]) → jsonb[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: oid[]) → oid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: pg_lsn[]) → pg_lsn[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: refcursor[]) → refcursor[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timetz[]) → timetz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: tuple[]) → tuple[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: varbit[]) → varbit[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
avg(arg1: decimal) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: float) → float

Calculates the average of the selected values.

+		Immutable
avg(arg1: int) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: interval) → interval

Calculates the average of the selected values.

+		Immutable
bit_and(arg1: int) → int

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_and(arg1: varbit) → varbit

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: int) → int

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: varbit) → varbit

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bool_and(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
bool_or(arg1: bool) → bool

Calculates the boolean value of ORing all selected values.

+		Immutable
concat_agg(arg1: bytes) → bytes

Concatenates all selected values.

+		Immutable
concat_agg(arg1: string) → string

Concatenates all selected values.

+		Immutable
corr(arg1: decimal, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
count(arg1: anyelement) → int

Calculates the number of selected elements.

+		Immutable
count_rows() → int

Calculates the number of rows.

+		Immutable
covar_pop(arg1: decimal, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
every(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
json_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
json_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
jsonb_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
jsonb_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
max(arg1: bool) → bool

Identifies the maximum selected value.

+		Immutable
max(arg1: bytes) → bytes

Identifies the maximum selected value.

+		Immutable
max(arg1: date) → date

Identifies the maximum selected value.

+		Immutable
max(arg1: decimal) → decimal

Identifies the maximum selected value.

+		Immutable
max(arg1: float) → float

Identifies the maximum selected value.

+		Immutable
max(arg1: inet) → inet

Identifies the maximum selected value.

+		Immutable
max(arg1: int) → int

Identifies the maximum selected value.

+		Immutable
max(arg1: interval) → interval

Identifies the maximum selected value.

+		Immutable
max(arg1: string) → string

Identifies the maximum selected value.

+		Immutable
max(arg1: time) → time

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamp) → timestamp

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamptz) → timestamptz

Identifies the maximum selected value.

+		Immutable
max(arg1: uuid) → uuid

Identifies the maximum selected value.

+		Immutable
max(arg1: anyenum) → anyenum

Identifies the maximum selected value.

+		Immutable
max(arg1: box2d) → box2d

Identifies the maximum selected value.

+		Immutable
max(arg1: collatedstring{*}) → collatedstring{*}

Identifies the maximum selected value.

+		Immutable
max(arg1: geography) → geography

Identifies the maximum selected value.

+		Immutable
max(arg1: geometry) → geometry

Identifies the maximum selected value.

+		Immutable
max(arg1: jsonb) → jsonb

Identifies the maximum selected value.

+		Immutable
max(arg1: oid) → oid

Identifies the maximum selected value.

+		Immutable
max(arg1: pg_lsn) → pg_lsn

Identifies the maximum selected value.

+		Immutable
max(arg1: timetz) → timetz

Identifies the maximum selected value.

+		Immutable
max(arg1: varbit) → varbit

Identifies the maximum selected value.

+		Immutable
min(arg1: bool) → bool

Identifies the minimum selected value.

+		Immutable
min(arg1: bytes) → bytes

Identifies the minimum selected value.

+		Immutable
min(arg1: date) → date

Identifies the minimum selected value.

+		Immutable
min(arg1: decimal) → decimal

Identifies the minimum selected value.

+		Immutable
min(arg1: float) → float

Identifies the minimum selected value.

+		Immutable
min(arg1: inet) → inet

Identifies the minimum selected value.

+		Immutable
min(arg1: int) → int

Identifies the minimum selected value.

+		Immutable
min(arg1: interval) → interval

Identifies the minimum selected value.

+		Immutable
min(arg1: string) → string

Identifies the minimum selected value.

+		Immutable
min(arg1: time) → time

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamp) → timestamp

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamptz) → timestamptz

Identifies the minimum selected value.

+		Immutable
min(arg1: uuid) → uuid

Identifies the minimum selected value.

+		Immutable
min(arg1: anyenum) → anyenum

Identifies the minimum selected value.

+		Immutable
min(arg1: box2d) → box2d

Identifies the minimum selected value.

+		Immutable
min(arg1: collatedstring{*}) → collatedstring{*}

Identifies the minimum selected value.

+		Immutable
min(arg1: geography) → geography

Identifies the minimum selected value.

+		Immutable
min(arg1: geometry) → geometry

Identifies the minimum selected value.

+		Immutable
min(arg1: jsonb) → jsonb

Identifies the minimum selected value.

+		Immutable
min(arg1: oid) → oid

Identifies the minimum selected value.

+		Immutable
min(arg1: pg_lsn) → pg_lsn

Identifies the minimum selected value.

+		Immutable
min(arg1: timetz) → timetz

Identifies the minimum selected value.

+		Immutable
min(arg1: varbit) → varbit

Identifies the minimum selected value.

+		Immutable
percentile_cont(arg1: float) → float

Continuous percentile: returns a float corresponding to the specified fraction in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float) → interval

Continuous percentile: returns an interval corresponding to the specified fraction in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_cont(arg1: float[]) → float[]

Continuous percentile: returns floats corresponding to the specified fractions in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float[]) → interval[]

Continuous percentile: returns intervals corresponding to the specified fractions in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_disc(arg1: float) → anyelement

Discrete percentile: returns the first input value whose position in the ordering equals or exceeds the specified fraction.

+		Immutable
percentile_disc(arg1: float[]) → anyelement

Discrete percentile: returns input values whose position in the ordering equals or exceeds the specified fractions.

+		Immutable
regr_avgx(arg1: decimal, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_count(arg1: decimal, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_intercept(arg1: decimal, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_r2(arg1: decimal, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_slope(arg1: decimal, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_sxx(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
sqrdiff(arg1: decimal) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: float) → float

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: int) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
st_collect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_extent(arg1: geometry) → box2d

Forms a Box2D that encapsulates all provided geometries.

+		Immutable
st_makeline(arg1: geometry) → geometry

Forms a LineString from Point, MultiPoint or LineStrings. Other shapes will be ignored.

+		Immutable
st_memcollect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_memunion(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
st_union(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
stddev(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: decimal) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: float) → float

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: int) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
string_agg(arg1: bytes, arg2: bytes) → bytes

Concatenates all selected values using the provided delimiter.

+		Immutable
string_agg(arg1: string, arg2: string) → string

Concatenates all selected values using the provided delimiter.

+		Immutable
sum(arg1: decimal) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: float) → float

Calculates the sum of the selected values.

+		Immutable
sum(arg1: int) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: interval) → interval

Calculates the sum of the selected values.

+		Immutable
sum_int(arg1: int) → int

Calculates the sum of the selected values.

+		Immutable
var_pop(arg1: decimal) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: float) → float

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: int) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_samp(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
variance(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
xor_agg(arg1: bytes) → bytes

Calculates the bitwise XOR of the selected values.

+		Immutable
xor_agg(arg1: int) → int

Calculates the bitwise XOR of the selected values.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-24.1/sql/functions.md b/src/current/_includes/cockroach-generated/release-24.1/sql/functions.md new file mode 100644 index 00000000000..df9e17317f3 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.1/sql/functions.md @@ -0,0 +1,3504 @@ +### Array functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_append(array: bool[], elem: bool) → bool[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: bytes[], elem: bytes) → bytes[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: date[], elem: date) → date[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: decimal[], elem: decimal) → decimal[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: float[], elem: float) → float[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: inet[], elem: inet) → inet[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: int[], elem: int) → int[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: interval[], elem: interval) → interval[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: string[], elem: string) → string[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: time[], elem: time) → time[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamp[], elem: timestamp) → timestamp[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamptz[], elem: timestamptz) → timestamptz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: uuid[], elem: uuid) → uuid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: anyenum[], elem: anyenum) → anyenum[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: box2d[], elem: box2d) → box2d[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geography[], elem: geography) → geography[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geometry[], elem: geometry) → geometry[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: jsonb[], elem: jsonb) → jsonb[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: oid[], elem: oid) → oid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: refcursor[], elem: refcursor) → refcursor[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timetz[], elem: timetz) → timetz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: tuple[], elem: tuple) → tuple[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: varbit[], elem: varbit) → varbit[]

Appends elem to array, returning the result.

+		Immutable
array_cat(left: bool[], right: bool[]) → bool[]

Appends two arrays.

+		Immutable
array_cat(left: bytes[], right: bytes[]) → bytes[]

Appends two arrays.

+		Immutable
array_cat(left: date[], right: date[]) → date[]

Appends two arrays.

+		Immutable
array_cat(left: decimal[], right: decimal[]) → decimal[]

Appends two arrays.

+		Immutable
array_cat(left: float[], right: float[]) → float[]

Appends two arrays.

+		Immutable
array_cat(left: inet[], right: inet[]) → inet[]

Appends two arrays.

+		Immutable
array_cat(left: int[], right: int[]) → int[]

Appends two arrays.

+		Immutable
array_cat(left: interval[], right: interval[]) → interval[]

Appends two arrays.

+		Immutable
array_cat(left: string[], right: string[]) → string[]

Appends two arrays.

+		Immutable
array_cat(left: time[], right: time[]) → time[]

Appends two arrays.

+		Immutable
array_cat(left: timestamp[], right: timestamp[]) → timestamp[]

Appends two arrays.

+		Immutable
array_cat(left: timestamptz[], right: timestamptz[]) → timestamptz[]

Appends two arrays.

+		Immutable
array_cat(left: uuid[], right: uuid[]) → uuid[]

Appends two arrays.

+		Immutable
array_cat(left: anyenum[], right: anyenum[]) → anyenum[]

Appends two arrays.

+		Immutable
array_cat(left: box2d[], right: box2d[]) → box2d[]

Appends two arrays.

+		Immutable
array_cat(left: geography[], right: geography[]) → geography[]

Appends two arrays.

+		Immutable
array_cat(left: geometry[], right: geometry[]) → geometry[]

Appends two arrays.

+		Immutable
array_cat(left: jsonb[], right: jsonb[]) → jsonb[]

Appends two arrays.

+		Immutable
array_cat(left: oid[], right: oid[]) → oid[]

Appends two arrays.

+		Immutable
array_cat(left: pg_lsn[], right: pg_lsn[]) → pg_lsn[]

Appends two arrays.

+		Immutable
array_cat(left: refcursor[], right: refcursor[]) → refcursor[]

Appends two arrays.

+		Immutable
array_cat(left: timetz[], right: timetz[]) → timetz[]

Appends two arrays.

+		Immutable
array_cat(left: tuple[], right: tuple[]) → tuple[]

Appends two arrays.

+		Immutable
array_cat(left: varbit[], right: varbit[]) → varbit[]

Appends two arrays.

+		Immutable
array_length(input: anyelement[], array_dimension: int) → int

Calculates the length of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_lower(input: anyelement[], array_dimension: int) → int

Calculates the minimum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_position(array: bool[], elem: bool) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bool[], elem: bool, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: bytes[], elem: bytes) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bytes[], elem: bytes, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: date[], elem: date) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: date[], elem: date, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: decimal[], elem: decimal) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: decimal[], elem: decimal, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: float[], elem: float) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: float[], elem: float, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: inet[], elem: inet) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: inet[], elem: inet, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: int[], elem: int) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: int[], elem: int, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: interval[], elem: interval) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: interval[], elem: interval, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: string[], elem: string) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: string[], elem: string, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: time[], elem: time) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: time[], elem: time, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timestamp[], elem: timestamp) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamp[], elem: timestamp, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: uuid[], elem: uuid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: uuid[], elem: uuid, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: anyenum[], elem: anyenum) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: anyenum[], elem: anyenum, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: box2d[], elem: box2d) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: box2d[], elem: box2d, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: geography[], elem: geography) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geography[], elem: geography, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: geometry[], elem: geometry) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geometry[], elem: geometry, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: jsonb[], elem: jsonb) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: jsonb[], elem: jsonb, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: oid[], elem: oid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: oid[], elem: oid, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: refcursor[], elem: refcursor) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: refcursor[], elem: refcursor, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timetz[], elem: timetz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timetz[], elem: timetz, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: tuple[], elem: tuple) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: tuple[], elem: tuple, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: varbit[], elem: varbit) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: varbit[], elem: varbit, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_positions(array: bool[], elem: bool) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: bytes[], elem: bytes) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: date[], elem: date) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: decimal[], elem: decimal) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: float[], elem: float) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: inet[], elem: inet) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: int[], elem: int) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: interval[], elem: interval) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: string[], elem: string) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: time[], elem: time) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamp[], elem: timestamp) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamptz[], elem: timestamptz) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: uuid[], elem: uuid) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: anyenum[], elem: anyenum) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: box2d[], elem: box2d) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geography[], elem: geography) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geometry[], elem: geometry) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: jsonb[], elem: jsonb) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: oid[], elem: oid) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: pg_lsn[], elem: pg_lsn) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: refcursor[], elem: refcursor) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timetz[], elem: timetz) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: tuple[], elem: tuple) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: varbit[], elem: varbit) → int[]

Returns and array of indexes of all occurrences of elem in array.

+		Immutable
array_prepend(elem: bool, array: bool[]) → bool[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: bytes, array: bytes[]) → bytes[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: date, array: date[]) → date[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: decimal, array: decimal[]) → decimal[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: float, array: float[]) → float[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: inet, array: inet[]) → inet[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: int, array: int[]) → int[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: interval, array: interval[]) → interval[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: string, array: string[]) → string[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: time, array: time[]) → time[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamp, array: timestamp[]) → timestamp[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamptz, array: timestamptz[]) → timestamptz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: uuid, array: uuid[]) → uuid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: anyenum, array: anyenum[]) → anyenum[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: box2d, array: box2d[]) → box2d[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geography, array: geography[]) → geography[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geometry, array: geometry[]) → geometry[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: jsonb, array: jsonb[]) → jsonb[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: oid, array: oid[]) → oid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: pg_lsn, array: pg_lsn[]) → pg_lsn[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: refcursor, array: refcursor[]) → refcursor[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timetz, array: timetz[]) → timetz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: tuple, array: tuple[]) → tuple[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: varbit, array: varbit[]) → varbit[]

Prepends elem to array, returning the result.

+		Immutable
array_remove(array: bool[], elem: bool) → bool[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: bytes[], elem: bytes) → bytes[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: date[], elem: date) → date[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: decimal[], elem: decimal) → decimal[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: float[], elem: float) → float[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: inet[], elem: inet) → inet[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: int[], elem: int) → int[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: interval[], elem: interval) → interval[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: string[], elem: string) → string[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: time[], elem: time) → time[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamp[], elem: timestamp) → timestamp[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamptz[], elem: timestamptz) → timestamptz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: uuid[], elem: uuid) → uuid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: anyenum[], elem: anyenum) → anyenum[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: box2d[], elem: box2d) → box2d[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geography[], elem: geography) → geography[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geometry[], elem: geometry) → geometry[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: jsonb[], elem: jsonb) → jsonb[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: oid[], elem: oid) → oid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: refcursor[], elem: refcursor) → refcursor[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timetz[], elem: timetz) → timetz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: tuple[], elem: tuple) → tuple[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: varbit[], elem: varbit) → varbit[]

Remove from array all elements equal to elem.

+		Immutable
array_replace(array: bool[], toreplace: bool, replacewith: bool) → bool[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: bytes[], toreplace: bytes, replacewith: bytes) → bytes[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: date[], toreplace: date, replacewith: date) → date[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: decimal[], toreplace: decimal, replacewith: decimal) → decimal[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: float[], toreplace: float, replacewith: float) → float[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: inet[], toreplace: inet, replacewith: inet) → inet[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: int[], toreplace: int, replacewith: int) → int[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: interval[], toreplace: interval, replacewith: interval) → interval[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: string[], toreplace: string, replacewith: string) → string[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: time[], toreplace: time, replacewith: time) → time[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamp[], toreplace: timestamp, replacewith: timestamp) → timestamp[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamptz[], toreplace: timestamptz, replacewith: timestamptz) → timestamptz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: uuid[], toreplace: uuid, replacewith: uuid) → uuid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: anyenum[], toreplace: anyenum, replacewith: anyenum) → anyenum[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: box2d[], toreplace: box2d, replacewith: box2d) → box2d[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geography[], toreplace: geography, replacewith: geography) → geography[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geometry[], toreplace: geometry, replacewith: geometry) → geometry[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: jsonb[], toreplace: jsonb, replacewith: jsonb) → jsonb[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: oid[], toreplace: oid, replacewith: oid) → oid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: pg_lsn[], toreplace: pg_lsn, replacewith: pg_lsn) → pg_lsn[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: refcursor[], toreplace: refcursor, replacewith: refcursor) → refcursor[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timetz[], toreplace: timetz, replacewith: timetz) → timetz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: tuple[], toreplace: tuple, replacewith: tuple) → tuple[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: varbit[], toreplace: varbit, replacewith: varbit) → varbit[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_to_string(input: anyelement[], delim: string) → string

Join an array into a string with a delimiter.

+		Stable
array_to_string(input: anyelement[], delimiter: string, null: string) → string

Join an array into a string with a delimiter, replacing NULLs with a null string.

+		Stable
array_upper(input: anyelement[], array_dimension: int) → int

Calculates the maximum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
cardinality(input: anyelement[]) → int

Calculates the number of elements contained in input

+		Immutable
jsonb_array_to_string_array(input: jsonb) → string[]

Convert a JSONB array into a string array.

+		Immutable
string_to_array(str: string, delimiter: string) → string[]

Split a string into components on a delimiter.

+		Immutable
string_to_array(str: string, delimiter: string, null: string) → string[]

Split a string into components on a delimiter with a specified string to consider NULL.

+		Immutable
+ +### BOOL functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Matches case insensetively unescaped with pattern using escape as an escape token.

+		Immutable
inet_contained_by_or_equals(val: inet, container: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_contains_or_equals(container: inet, val: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_same_family(val: inet, val: inet) → bool

Checks if two IP addresses are of the same IP family.

+		Immutable
like_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
not_ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches case insensetively with pattern using escape as an escape token.

+		Immutable
not_like_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
not_similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
+ +### Comparison functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
greatest(anyelement...) → anyelement

Returns the element with the greatest value.

+		Immutable
least(anyelement...) → anyelement

Returns the element with the lowest value.

+		Immutable
num_nonnulls(anyelement...) → int

Returns the number of nonnull arguments.

+		Immutable
num_nulls(anyelement...) → int

Returns the number of null arguments.

+		Immutable
+ +### Cryptographic functions + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crypt(password: string, salt: string) → string

Generates a hash based on a password and salt. The hash algorithm and number of rounds if applicable are encoded in the salt.

+		Immutable
decrypt(data: bytes, key: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
decrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
digest(data: bytes, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
digest(data: string, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
encrypt(data: bytes, key: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
encrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
gen_random_bytes(count: int) → bytes

Returns count cryptographically strong random bytes. At most 1024 bytes can be extracted at a time.

+		Volatile
gen_salt(type: string) → string

Generates a salt for input into the crypt function using the default number of rounds.

+		Volatile
gen_salt(type: string, iter_count: int) → string

Generates a salt for input into the crypt function using iter_count number of rounds.

+		Volatile
hmac(data: bytes, key: bytes, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
hmac(data: string, key: string, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
+ +### DECIMAL functions + + + + + +
Function → ReturnsDescriptionVolatility
hlc_to_timestamp(hlc: decimal) → timestamptz

Returns a TimestampTZ representation of a CockroachDB HLC in decimal form.

+

Note that a TimestampTZ has less precision than a CockroachDB HLC. It is intended as +a convenience function to display HLCs in a print-friendly form. Use the decimal +value if you rely on the HLC for accuracy.

+		Immutable
+ +### Date and time functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
age(end: timestamptz, begin: timestamptz) → interval

Calculates the interval between begin and end, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use the timestamptz subtraction operator.

+		Immutable
age(val: timestamptz) → interval

Calculates the interval between val and the current time, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use now() - timestamptz.

+		Stable
clock_timestamp() → timestamp

Returns the current system time on one of the cluster nodes.

+		Volatile
clock_timestamp() → timestamptz

Returns the current system time on one of the cluster nodes.

+		Volatile
current_date() → date

Returns the date of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_timestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
date_part(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
date_part(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
date_trunc(element: string, input: date) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: interval) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: time) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero.

+

Compatible elements: hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamp) → timestamp

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamptz) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: timestamptz, timezone: string) → timestamptz

Truncates input to precision element in the specified timezone. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
experimental_follower_read_timestamp() → timestamptz

Same as follower_read_timestamp. This name is deprecated.

+		Volatile
experimental_strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
extract(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
extract(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
extract_duration(element: string, input: interval) → int

Extracts element from input. +Compatible elements: hour, minute, second, millisecond, microsecond. +This is deprecated in favor of extract which supports duration.

+		Immutable
follower_read_timestamp() → timestamptz

Returns a timestamp which is very likely to be safe to perform +against a follower replica.

+

This function is intended to be used with an AS OF SYSTEM TIME clause to perform +historical reads against a time which is recent but sufficiently old for reads +to be performed against the closest replica as opposed to the currently +leaseholder for a given range.

+

Note that this function requires an enterprise license on a CCL distribution to +return a result that is less likely the closest replica. It is otherwise +hardcoded as -4.8s from the statement time, which may not result in reading from the +nearest replica.

+		Volatile
localtimestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
make_date(year: int, month: int, day: int) → date

Create date (formatted according to ISO 8601) from year, month, and day fields (negative years signify BC).

+		Immutable
make_timestamp(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamp

Create timestamp (formatted according to ISO 8601) from year, month, day, hour, minute, and seconds fields (negative years signify BC).

+		Immutable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float, timezone: string) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
now() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
overlaps(s1: date, e1: date, s1: date, e2: date) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: date, e1: interval, s1: date, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: interval, s1: time, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: time, s1: time, e2: time) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: interval, s1: timestamp, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: timestamp, s1: timestamp, e2: timestamp) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamptz, e1: interval, s1: timestamptz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Stable
overlaps(s1: timestamptz, e1: timestamptz, s1: timestamptz, e2: timestamptz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: interval, s1: timetz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: timetz, s1: timetz, e2: timetz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
statement_timestamp() → timestamp

Returns the start time of the current statement.

+		Stable
statement_timestamp() → timestamptz

Returns the start time of the current statement.

+		Stable
strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
timeofday() → string

Returns the current system time on one of the cluster nodes as a string.

+		Stable
timezone(timezone: string, time: time) → timetz

Treat given time without time zone as located in the specified time zone.

+		Stable
timezone(timezone: string, timestamp: timestamp) → timestamptz

Treat given time stamp without time zone as located in the specified time zone.

+		Immutable
timezone(timezone: string, timestamptz: timestamptz) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Immutable
timezone(timezone: string, timestamptz_string: string) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Stable
timezone(timezone: string, timetz: timetz) → timetz

Convert given time with time zone to the new time zone.

+		Stable
to_char(date: date) → string

Convert an date to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(date: date, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_char(interval: interval) → string

Convert an interval to a string assuming the Postgres IntervalStyle.

+		Immutable
to_char(interval: interval, format: string) → string

Convert an interval to a string using the given format.

+		Stable
to_char(timestamp: timestamp) → string

Convert an timestamp to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(timestamp: timestamp, format: string) → string

Convert an timestamp to a string using the given format.

+		Stable
to_char(timestamptz: timestamptz, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_timestamp(timestamp: float) → timestamptz

Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to timestamp with time zone.

+		Immutable
transaction_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
with_max_staleness(max_staleness: interval) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_max_staleness(max_staleness: interval, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
+ +### Enum functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
enum_first(val: anyenum) → anyenum

Returns the first value of the input enum type.

+		Stable
enum_last(val: anyenum) → anyenum

Returns the last value of the input enum type.

+		Stable
enum_range(lower: anyenum, upper: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array between the two arguments (inclusive).

+		Stable
enum_range(val: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array.

+		Stable
+ +### FLOAT functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abs(val: decimal) → decimal

Calculates the absolute value of val.

+		Immutable
abs(val: float) → float

Calculates the absolute value of val.

+		Immutable
abs(val: int) → int

Calculates the absolute value of val.

+		Immutable
acos(val: float) → float

Calculates the inverse cosine of val.

+		Immutable
acosd(val: float) → float

Calculates the inverse cosine of val with the result in degrees

+		Immutable
acosh(val: float) → float

Calculates the inverse hyperbolic cosine of val.

+		Immutable
asin(val: float) → float

Calculates the inverse sine of val.

+		Immutable
asind(val: float) → float

Calculates the inverse sine of val with the result in degrees.

+		Immutable
asinh(val: float) → float

Calculates the inverse hyperbolic sine of val.

+		Immutable
atan(val: float) → float

Calculates the inverse tangent of val.

+		Immutable
atan2(x: float, y: float) → float

Calculates the inverse tangent of x/y.

+		Immutable
atan2d(x: float, y: float) → float

Calculates the inverse tangent of x/y with the result in degrees

+		Immutable
atand(val: float) → float

Calculates the inverse tangent of val with the result in degrees.

+		Immutable
atanh(val: float) → float

Calculates the inverse hyperbolic tangent of val.

+		Immutable
cbrt(val: decimal) → decimal

Calculates the cube root (∛) of val.

+		Immutable
cbrt(val: float) → float

Calculates the cube root (∛) of val.

+		Immutable
ceil(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
cos(val: float) → float

Calculates the cosine of val.

+		Immutable
cosd(val: float) → float

Calculates the cosine of val where val is in degrees.

+		Immutable
cosh(val: float) → float

Calculates the hyperbolic cosine of val.

+		Immutable
cot(val: float) → float

Calculates the cotangent of val.

+		Immutable
cotd(val: float) → float

Calculates the cotangent of val where val is in degrees.

+		Immutable
degrees(val: float) → float

Converts val as a radian value to a degree value.

+		Immutable
div(x: decimal, y: decimal) → decimal

Calculates the integer quotient of x/y.

+		Immutable
div(x: float, y: float) → float

Calculates the integer quotient of x/y.

+		Immutable
div(x: int, y: int) → int

Calculates the integer quotient of x/y.

+		Immutable
exp(val: decimal) → decimal

Calculates e ^ val.

+		Immutable
exp(val: float) → float

Calculates e ^ val.

+		Immutable
floor(val: decimal) → decimal

Calculates the largest integer not greater than val.

+		Immutable
floor(val: float) → float

Calculates the largest integer not greater than val.

+		Immutable
floor(val: int) → float

Calculates the largest integer not greater than val.

+		Immutable
isnan(val: decimal) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
isnan(val: float) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
ln(val: decimal) → decimal

Calculates the natural log of val.

+		Immutable
ln(val: float) → float

Calculates the natural log of val.

+		Immutable
log(b: decimal, x: decimal) → decimal

Calculates the base b log of val.

+		Immutable
log(b: float, x: float) → float

Calculates the base b log of val.

+		Immutable
log(val: decimal) → decimal

Calculates the base 10 log of val.

+		Immutable
log(val: float) → float

Calculates the base 10 log of val.

+		Immutable
mod(x: decimal, y: decimal) → decimal

Calculates x%y.

+		Immutable
mod(x: float, y: float) → float

Calculates x%y.

+		Immutable
mod(x: int, y: int) → int

Calculates x%y.

+		Immutable
pi() → float

Returns the value for pi (3.141592653589793).

+		Immutable
pow(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
pow(x: float, y: float) → float

Calculates x^y.

+		Immutable
pow(x: int, y: int) → int

Calculates x^y.

+		Immutable
power(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
power(x: float, y: float) → float

Calculates x^y.

+		Immutable
power(x: int, y: int) → int

Calculates x^y.

+		Immutable
radians(val: float) → float

Converts val as a degree value to a radians value.

+		Immutable
random() → float

Returns a random floating-point number between 0 (inclusive) and 1 (exclusive). Note that the value contains at most 53 bits of randomness.

+		Volatile
round(input: decimal, decimal_accuracy: int) → decimal

Keeps decimal_accuracy number of figures to the right of the zero position in input using half away from zero rounding. If decimal_accuracy is not in the range -2^31…(2^31-1), the results are undefined.

+		Immutable
round(input: float, decimal_accuracy: int) → float

Keeps decimal_accuracy number of figures to the right of the zero position in input using half to even (banker’s) rounding.

+		Immutable
round(val: decimal) → decimal

Rounds val to the nearest integer, half away from zero: round(+/-2.4) = +/-2, round(+/-2.5) = +/-3.

+		Immutable
round(val: float) → float

Rounds val to the nearest integer using half to even (banker’s) rounding.

+		Immutable
setseed(seed: float) → void

Sets the seed for subsequent random() calls in this session (value between -1.0 and 1.0, inclusive). There are no guarantees as to how this affects the seed of random() calls that appear in the same query as setseed().

+		Volatile
sign(val: decimal) → decimal

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: float) → float

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: int) → int

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sin(val: float) → float

Calculates the sine of val.

+		Immutable
sind(val: float) → float

Calculates the sine of val where val is in degrees.

+		Immutable
sinh(val: float) → float

Calculates the hyperbolic sine of val.

+		Immutable
sqrt(val: decimal) → decimal

Calculates the square root of val.

+		Immutable
sqrt(val: float) → float

Calculates the square root of val.

+		Immutable
tan(val: float) → float

Calculates the tangent of val.

+		Immutable
tand(val: float) → float

Calculates the tangent of val where val is in degrees.

+		Immutable
tanh(val: float) → float

Calculates the hyperbolic tangent of val.

+		Immutable
trunc(val: decimal) → decimal

Truncates the decimal values of val.

+		Immutable
trunc(val: decimal, scale: int) → decimal

Truncate val to scale decimal places

+		Immutable
trunc(val: float) → float

Truncates the decimal values of val.

+		Immutable
+ +### Full Text Search functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
phraseto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The <-> operator is inserted between each token in the input.

+		Immutable
phraseto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The <-> operator is inserted between each token in the input.

+		Stable
plainto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The & operator is inserted between each token in the input.

+		Immutable
plainto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The & operator is inserted between each token in the input.

+		Stable
to_tsquery(config: string, text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the specified configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Immutable
to_tsquery(text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the default configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Stable
to_tsvector(config: string, text: string) → tsvector

Converts text to a tsvector, normalizing words according to the specified configuration. Position information is included in the result.

+		Immutable
to_tsvector(text: string) → tsvector

Converts text to a tsvector, normalizing words according to the default configuration. Position information is included in the result.

+		Stable
ts_parse(parser_name: string, document: string) → tuple{int AS tokid, string AS token}

ts_parse parses the given document and returns a series of records, one for each token produced by parsing. Each record includes a tokid showing the assigned token type and a token which is the text of the token.

+		Stable
ts_rank(vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
+ +### Fuzzy String Matching functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
levenshtein(source: string, target: string) → int

Calculates the Levenshtein distance between two strings. Maximum input length is 255 characters.

+		Immutable
levenshtein(source: string, target: string, ins_cost: int, del_cost: int, sub_cost: int) → int

Calculates the Levenshtein distance between two strings. The cost parameters specify how much to charge for each edit operation. Maximum input length is 255 characters.

+		Immutable
metaphone(source: string, max_output_length: int) → string

Convert a string to its Metaphone code. Maximum input length is 255 characters

+		Immutable
soundex(source: string) → string

Convert a string to its Soundex code.

+		Immutable
+ +### ID generation functions + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
experimental_uuid_v4() → bytes

Returns a UUID.

+		Volatile
gen_random_ulid() → uuid

Generates a random ULID and returns it as a value of UUID type.

+		Volatile
gen_random_uuid() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
unique_rowid() → int

Returns a unique ID used by CockroachDB to generate unique row IDs if a Primary Key isn’t defined for the table. The value is a combination of the insert timestamp and the ID of the node executing the statement, which guarantees this combination is globally unique. However, there can be gaps and the order is not completely guaranteed.

+		Volatile
unordered_unique_rowid() → int

Returns a unique ID. The value is a combination of the insert timestamp (bit-reversed) and the ID of the node executing the statement, which guarantees this combination is globally unique. The way it is generated is statistically likely to not have any ordering relative to previously generated values.

+		Volatile
uuid_generate_v1() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. To avoid exposing the server’s real MAC address, this uses a random MAC address and a timestamp. Essentially, this is an alias for uuid_generate_v1mc.

+		Volatile
uuid_generate_v1mc() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. This uses a random MAC address and a timestamp.

+		Volatile
uuid_generate_v3(namespace: uuid, name: string) → uuid

Generates a version 3 UUID in the given namespace using the specified input name, with md5 as the hashing method. The namespace should be one of the special constants produced by the uuid_ns_*() functions.

+		Immutable
uuid_generate_v4() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
uuid_generate_v5(namespace: uuid, name: string) → uuid

Generates a version 5 UUID in the given namespace using the specified input name. This is similar to a version 3 UUID, except it uses SHA-1 for hashing.

+		Immutable
uuid_nil() → uuid

Returns a nil UUID constant.

+		Immutable
uuid_ns_dns() → uuid

Returns a constant designating the DNS namespace for UUIDs.

+		Immutable
uuid_ns_oid() → uuid

Returns a constant designating the ISO object identifier (OID) namespace for UUIDs. These are unrelated to the OID type used internally in the database.

+		Immutable
uuid_ns_url() → uuid

Returns a constant designating the URL namespace for UUIDs.

+		Immutable
uuid_ns_x500() → uuid

Returns a constant designating the X.500 distinguished name (DN) namespace for UUIDs.

+		Immutable
uuid_v4() → bytes

Returns a UUID.

+		Volatile
+ +### INET functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abbrev(val: inet) → string

Converts the combined IP address and prefix length to an abbreviated display format as text.For INET types, this will omit the prefix length if it’s not the default (32 or IPv4, 128 for IPv6)

+

For example, abbrev('192.168.1.2/24') returns '192.168.1.2/24'

+		Immutable
broadcast(val: inet) → inet

Gets the broadcast address for the network address represented by the value.

+

For example, broadcast('192.168.1.2/24') returns '192.168.1.255/24'

+		Immutable
family(val: inet) → int

Extracts the IP family of the value; 4 for IPv4, 6 for IPv6.

+

For example, family('::1') returns 6

+		Immutable
host(val: inet) → string

Extracts the address part of the combined address/prefixlen value as text.

+

For example, host('192.168.1.2/16') returns '192.168.1.2'

+		Immutable
hostmask(val: inet) → inet

Creates an IP host mask corresponding to the prefix length in the value.

+

For example, hostmask('192.168.1.2/16') returns '0.0.255.255'

+		Immutable
masklen(val: inet) → int

Retrieves the prefix length stored in the value.

+

For example, masklen('192.168.1.2/16') returns 16

+		Immutable
netmask(val: inet) → inet

Creates an IP network mask corresponding to the prefix length in the value.

+

For example, netmask('192.168.1.2/16') returns '255.255.0.0'

+		Immutable
set_masklen(val: inet, prefixlen: int) → inet

Sets the prefix length of val to prefixlen.

+

For example, set_masklen('192.168.1.2', 16) returns '192.168.1.2/16'.

+		Immutable
+ +### INT functions + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crc32c(bytes...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32c(string...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32ieee(bytes...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
crc32ieee(string...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
fnv32(bytes...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32(string...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32a(bytes...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv32a(string...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64(bytes...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64(string...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64a(bytes...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64a(string...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
width_bucket(operand: decimal, b1: decimal, b2: decimal, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2.

+		Immutable
width_bucket(operand: int, b1: int, b2: int, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2.

+		Immutable
width_bucket(operand: anyelement, thresholds: anyelement[]) → int

return the bucket number to which operand would be assigned given an array listing the lower bounds of the buckets; returns 0 for an input less than the first lower bound; the thresholds array must be sorted, smallest first, or unexpected results will be obtained

+		Immutable
+ +### JSONB functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_to_json(array: anyelement[]) → jsonb

Returns the array as JSON or JSONB.

+		Stable
array_to_json(array: anyelement[], pretty_bool: bool) → jsonb

Returns the array as JSON or JSONB.

+		Stable
json_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
json_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
json_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
json_build_array(anyelement...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
json_build_object(anyelement...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
json_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
json_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
json_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
json_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
json_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
json_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
json_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
json_remove_path(val: jsonb, path: string[]) → jsonb

Remove the specified path from the JSON object.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
json_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
json_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
json_valid(string: string) → bool

Returns whether the given string is a valid JSON or not

+		Immutable
jsonb_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
jsonb_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
jsonb_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
jsonb_build_array(anyelement...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
jsonb_build_object(anyelement...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
jsonb_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
jsonb_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
jsonb_exists_any(json: jsonb, array: string[]) → bool

Returns whether any of the strings in the text array exist as top-level keys or array elements

+		Immutable
jsonb_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments. new_val will be inserted before path target.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb, insert_after: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If insert_after is true (default is false), new_val will be inserted after path target.

+		Immutable
jsonb_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
jsonb_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
jsonb_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
jsonb_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
jsonb_pretty(val: jsonb) → string

Returns the given JSON value as a STRING indented and with newlines.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
jsonb_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
jsonb_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
row_to_json(row: tuple) → jsonb

Returns the row as a JSON object.

+		Stable
to_json(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
to_jsonb(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
+ +### Multi-region functions + + + + + + + +
Function → ReturnsDescriptionVolatility
default_to_database_primary_region(val: string) → string

Returns the given region if the region has been added to the current database. +Otherwise, this will return the primary region of the current database. +This will error if the current database is not a multi-region database.

+		Stable
gateway_region() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
rehome_row() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
+ +### STRING[] functions + + + + + + +
Function → ReturnsDescriptionVolatility
regexp_split_to_array(string: string, pattern: string) → string[]

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_array(string: string, pattern: string, flags: string) → string[]

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
+ +### Sequence functions + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
currval(sequence_name: string) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
currval(sequence_name: regclass) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
lastval() → int

Return value most recently obtained with nextval in this session.

+		Volatile
nextval(sequence_name: string) → int

Advances the given sequence and returns its new value.

+		Volatile
nextval(sequence_name: regclass) → int

Advances the given sequence and returns its new value.

+		Volatile
setval(sequence_name: string, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: string, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
setval(sequence_name: regclass, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: regclass, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
+ +### Set-returning functions + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
aclexplode(aclitems: string[]) → tuple{oid AS grantor, oid AS grantee, string AS privilege_type, bool AS is_grantable}

Produces a virtual table containing aclitem stuff (returns no rows as this feature is unsupported in CockroachDB)

+		Stable
generate_series(start: int, end: int) → int

Produces a virtual table containing the integer values from start to end, inclusive.

+		Immutable
generate_series(start: int, end: int, step: int) → int

Produces a virtual table containing the integer values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamp, end: timestamp, step: interval) → timestamp

Produces a virtual table containing the timestamp values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamptz, end: timestamptz, step: interval) → timestamptz

Produces a virtual table containing the timestampTZ values from start to end, inclusive, by increment of step.

+		Immutable
generate_subscripts(array: anyelement[]) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int, reverse: bool) → int

Returns a series comprising the given array’s subscripts.

+

When reverse is true, the series is returned in reverse order.

+		Immutable
information_schema._pg_expandarray(input: anyelement[]) → tuple{anyelement AS x, int AS n}

Returns the input array as a set of rows with an index

+		Immutable
json_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
json_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
json_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
jsonb_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
jsonb_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
jsonb_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
pg_get_keywords() → tuple{string AS word, string AS catcode, string AS catdesc}

Produces a virtual table containing the keywords known to the SQL parser.

+		Immutable
pg_options_to_table(options: string[]) → tuple{string AS option_name, string AS option_value}

Converts the options array format to a table.

+		Stable
regexp_split_to_table(string: string, pattern: string) → string

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_table(string: string, pattern: string, flags: string) → string

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
unnest(anyelement[], anyelement[], anyelement[]...) → tuple{anyelement AS unnest, anyelement AS unnest, anyelement AS unnest}

Returns the input arrays as a set of rows

+		Immutable
unnest(input: anyelement[]) → anyelement

Returns the input array as a set of rows

+		Immutable
workload_index_recs() → string

Returns set of index recommendations

+		Immutable
workload_index_recs(timestamptz: timestamptz) → string

Returns set of index recommendations

+		Immutable
+ +### Spatial functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
_st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
geometrytype(geometry: geometry) → string

Returns the type of geometry as a string.

+

This function utilizes the GEOS module.

+		Immutable
geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
postgis_addbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_dropbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_extensions_upgrade() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_full_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_geos_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_getbbox(geometry: geometry) → box2d

Returns a box2d encapsulating the given Geometry.

+		Immutable
postgis_hasbbox(geometry: geometry) → bool

Returns whether a given Geometry has a bounding box. False for points and empty geometries; always true otherwise.

+		Immutable
postgis_lib_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_lib_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_liblwgeom_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_libxml_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_proj_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_installed() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_released() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_wagyu_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
st_addmeasure(geometry: geometry, start: float, end: float) → geometry

Returns a copy of a LineString or MultiLineString with measure coordinates linearly interpolated between the specified start and end values. Any existing M coordinates will be overwritten.

+		Immutable
st_addpoint(line_string: geometry, point: geometry) → geometry

Adds a Point to the end of a LineString.

+		Immutable
st_addpoint(line_string: geometry, point: geometry, index: int) → geometry

Adds a Point to a LineString at the given 0-based index (-1 to append).

+		Immutable
st_affine(geometry: geometry, a: float, b: float, c: float, d: float, e: float, f: float, g: float, h: float, i: float, x_off: float, y_off: float, z_off: float) → geometry

Applies a 3D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b c x_off \ / x
+| d e f y_off | | y | +| g h i z_off | | z | +\ 0 0 0 1 / \ 0 /

+		Immutable
st_affine(geometry: geometry, a: float, b: float, d: float, e: float, x_off: float, y_off: float) → geometry

Applies a 2D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b x_off \ / x
+| d e y_off | | y | +\ 0 0 1 / \ 0 /

+		Immutable
st_angle(line1: geometry, line2: geometry) → float

Returns the clockwise angle between two LINESTRING geometries, treating them as vectors between their start- and endpoints. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry) → float

Returns the clockwise angle between the vectors formed by point2,point1 and point2,point3. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry, point4: geometry) → float

Returns the clockwise angle between the vectors formed by point1,point2 and point3,point4. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_area(geography: geography) → float

Returns the area of the given geography in meters^2. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geography: geography, use_spheroid: bool) → float

Returns the area of the given geography in meters^2.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_area(geometry_str: string) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_area2d(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_asbinary(geography: geography) → bytes

Returns the WKB representation of a given Geography.

+		Immutable
st_asbinary(geography: geography, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asbinary(geometry: geometry) → bytes

Returns the WKB representation of a given Geometry.

+		Immutable
st_asbinary(geometry: geometry, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asencodedpolyline(geometry: geometry) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Preserves 5 decimal places.

+		Immutable
st_asencodedpolyline(geometry: geometry, precision: int4) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+		Immutable
st_asewkb(geography: geography) → bytes

Returns the EWKB representation of a given Geography.

+		Immutable
st_asewkb(geometry: geometry) → bytes

Returns the EWKB representation of a given Geometry.

+		Immutable
st_asewkt(geography: geography) → string

Returns the EWKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_asewkt(geography: geography, max_decimal_digits: int) → string

Returns the EWKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry: geometry) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_asewkt(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry_str: string) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asewkt(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geography: geography) → string

Returns the GeoJSON representation of a given Geography. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option (default for Geography)
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326
    • +
+		Immutable
st_asgeojson(geometry: geometry) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+		Immutable
st_asgeojson(geometry_str: string) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(row: tuple) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(row: tuple, geo_column: string) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. Coordinates have a maximum of 9 decimal digits.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int, pretty: bool) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value. Output will be pretty printed in JSON if pretty is true.

+		Stable
st_ashexewkb(geography: geography) → string

Returns the EWKB representation in hex of a given Geography.

+		Immutable
st_ashexewkb(geography: geography, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexewkb(geometry: geometry) → string

Returns the EWKB representation in hex of a given Geometry.

+		Immutable
st_ashexewkb(geometry: geometry, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexwkb(geography: geography) → string

Returns the WKB representation in hex of a given Geography.

+		Immutable
st_ashexwkb(geometry: geometry) → string

Returns the WKB representation in hex of a given Geometry.

+		Immutable
st_askml(geography: geography) → string

Returns the KML representation of a given Geography.

+		Immutable
st_askml(geometry: geometry) → string

Returns the KML representation of a given Geometry.

+		Immutable
st_askml(geometry_str: string) → string

Returns the KML representation of a given Geometry.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping. +Uses 4096 as the tile extent size in tile coordinate space.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int, clip: bool) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds if required.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry can be transformed, and clipped if required.

+		Immutable
st_astext(geography: geography) → string

Returns the WKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_astext(geography: geography, max_decimal_digits: int) → string

Returns the WKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry: geometry) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_astext(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry_str: string) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astext(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int, precision_m: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_azimuth(geography_a: geography, geography_b: geography) → float

Returns the azimuth in radians of the segment defined by the given point geographies, or NULL if the two points are coincident. It is solved using the Inverse geodesic problem.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_azimuth(geometry_a: geometry, geometry_b: geometry) → float

Returns the azimuth in radians of the segment defined by the given point geometries, or NULL if the two points are coincident.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+		Immutable
st_bdpolyfromtext(str: string, srid: int) → geometry

Returns a Polygon from multilinestring WKT with a SRID. If the input is not a multilinestring an error will be thrown.

+		Immutable
st_boundary(geometry: geometry) → geometry

Returns the closure of the combinatorial boundary of this Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_box2dfromgeohash(geohash: string) → box2d

Return a Box2D from a GeoHash string with max precision.

+		Immutable
st_box2dfromgeohash(geohash: string, precision: int) → box2d

Return a Box2D from a GeoHash string with supplied precision.

+		Immutable
st_buffer(geography: geography, distance: float) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, buffer_style_params: string) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, quad_segs: int) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geometry: geometry, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry_str: string, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_centroid(geography: geography) → geography

Returns the centroid of given geography. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geography: geography, use_spheroid: bool) → geography

Returns the centroid of given geography.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geometry: geometry) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_centroid(geometry_str: string) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_clipbybox2d(geometry: geometry, box2d: box2d) → geometry

Clips the geometry to conform to the bounding box specified by box2d.

+		Immutable
st_closestpoint(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the 2-dimensional point on geometry_a that is closest to geometry_b. This is the first point of the shortest line.

+		Immutable
st_collectionextract(geometry: geometry, type: int) → geometry

Given a collection, returns a multitype consisting only of elements of the specified type. If there are no elements of the given type, an EMPTY geometry is returned. Types are specified as 1=POINT, 2=LINESTRING, 3=POLYGON - other types are not supported.

+		Immutable
st_collectionhomogenize(geometry: geometry) → geometry

Returns the “simplest” representation of a collection’s contents. Collections of a single type will be returned as an appopriate multitype, or a singleton if it only contains a single geometry.

+		Immutable
st_combinebbox(box2d: box2d, geometry: geometry) → box2d

Combines the current bounding box with the bounding box of the Geometry.

+		Immutable
st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_convexhull(geometry: geometry) → geometry

Returns a geometry that represents the Convex Hull of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_coorddim(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_difference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the difference of two Geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_dimension(geometry: geometry) → int

Returns the number of topological dimensions of a given Geometry.

+		Immutable
st_disjoint(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a does not overlap, touch or is within geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_distance(geography_a: geography, geography_b: geography) → float

Returns the distance in meters between geography_a and geography_b. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geography_a: geography, geography_b: geography, use_spheroid: bool) → float

Returns the distance in meters between geography_a and geography_b.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance between the given geometries.

+		Immutable
st_distance(geometry_a_str: string, geometry_b_str: string) → float

Returns the distance between the given geometries.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_distancesphere(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_distancespheroid(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a spheroid.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_endpoint(geometry: geometry) → geometry

Returns the last point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_envelope(box2d: box2d) → geometry

Returns a bounding geometry for the given box.

+		Immutable
st_envelope(geometry: geometry) → geometry

Returns a bounding envelope for the given geometry.

+

For geometries which have a POINT or LINESTRING bounding box (i.e. is a single point +or a horizontal or vertical line), a POINT or LINESTRING is returned. Otherwise, the +returned POLYGON will be ordered Bottom Left, Top Left, Top Right, Bottom Right, +Bottom Left.

+		Immutable
st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string, parent_only: bool) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+

The parent_only boolean is always ignored.

+		Stable
st_estimatedextent(table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_expand(box2d: box2d, delta: float) → box2d

Extends the box2d by delta units across all dimensions.

+		Immutable
st_expand(box2d: box2d, delta_x: float, delta_y: float) → box2d

Extends the box2d by delta_x units in the x dimension and delta_y units in the y dimension.

+		Immutable
st_expand(geometry: geometry, delta: float) → geometry

Extends the bounding box represented by the geometry by delta units across all dimensions, returning a Polygon representing the new bounding box.

+		Immutable
st_expand(geometry: geometry, delta_x: float, delta_y: float) → geometry

Extends the bounding box represented by the geometry by delta_x units in the x dimension and delta_y units in the y dimension, returning a Polygon representing the new bounding box.

+		Immutable
st_exteriorring(geometry: geometry) → geometry

Returns the exterior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon.

+		Immutable
st_flipcoordinates(geometry: geometry) → geometry

Returns a new geometry with the X and Y axes flipped.

+		Immutable
st_force2d(geometry: geometry) → geometry

Returns a Geometry that is forced into XY layout with any Z or M dimensions discarded.

+		Immutable
st_force3d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to 0. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry, defaultM: float) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to the specified default M value. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force4d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZM layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float, defaultM: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified Z value. If a M coordinate doesn’t exist, it will be set to the specified M value.

+		Immutable
st_forcecollection(geometry: geometry) → geometry

Converts the geometry into a GeometryCollection.

+		Immutable
st_forcepolygonccw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_forcepolygoncw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Frechet distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Frechet distance between the given geometries, with the given segment densification (range 0.0-1.0, -1 to disable).

+

Smaller densify_frac gives a more accurate Fréchet distance. However, the computation time and memory usage increases with the square of the number of subsegments.

+

This function utilizes the GEOS module.

+		Immutable
st_generatepoints(geometry: geometry, npoints: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. Uses system time as a seed. +The requested number of points must be not larger than 65336.

+		Volatile
st_generatepoints(geometry: geometry, npoints: int4, seed: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. +The requested number of points must be not larger than 65336.

+		Immutable
st_geogfromewkb(val: bytes) → geography

Returns the Geography from an EWKB representation.

+		Immutable
st_geogfromewkt(val: string) → geography

Returns the Geography from an EWKT representation.

+		Immutable
st_geogfromgeojson(val: string) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromgeojson(val: jsonb) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geogfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geogfromwkb(bytes: bytes, srid: int) → geography

Returns the Geography from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geogfromwkb(val: bytes) → geography

Returns the Geography from a WKB (or EWKB) representation.

+		Immutable
st_geographyfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geographyfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geohash(geography: geography) → string

Returns a GeoHash representation of the geeographywith full precision if a point is provided, or with variable precision based on the size of the feature.

+		Immutable
st_geohash(geography: geography, precision: int) → string

Returns a GeoHash representation of the geography with the supplied precision.

+		Immutable
st_geohash(geometry: geometry) → string

Returns a GeoHash representation of the geometry with full precision if a point is provided, or with variable precision based on the size of the feature. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geohash(geometry: geometry, precision: int) → string

Returns a GeoHash representation of the geometry with the supplied precision. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geomcollfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomcollfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geometryfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geometryfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geometryn(geometry: geometry, n: int) → geometry

Returns the n-th Geometry (1-indexed). Returns NULL if out of bounds.

+		Immutable
st_geometrytype(geometry: geometry) → string

Returns the type of geometry as a string prefixed with ST_.

+

This function utilizes the GEOS module.

+		Immutable
st_geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
st_geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
st_geomfromgeohash(geohash: string) → geometry

Return a POLYGON Geometry from a GeoHash string with max precision.

+		Immutable
st_geomfromgeohash(geohash: string, precision: int) → geometry

Return a POLYGON Geometry from a GeoHash string with supplied precision.

+		Immutable
st_geomfromgeojson(val: string) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromgeojson(val: jsonb) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geomfromwkb(bytes: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geomfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_hasarc(geometry: geometry) → bool

Returns whether there is a CIRCULARSTRING in the geometry.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Hausdorff distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Hausdorff distance between the given geometries, with the given segment densification (range 0.0-1.0).

+

This function utilizes the GEOS module.

+		Immutable
st_interiorringn(geometry: geometry, n: int) → geometry

Returns the n-th (1-indexed) interior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon, or the ring does not exist.

+		Immutable
st_intersection(geography_a: geography, geography_b: geography) → geography

Returns the point intersections of the given geographies.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a_str: string, geometry_b_str: string) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_isclosed(geometry: geometry) → bool

Returns whether the geometry is closed as defined by whether the start and end points are coincident. Points are considered closed, empty geometries are not. For collections and multi-types, all members must be closed, as must all polygon rings.

+		Immutable
st_iscollection(geometry: geometry) → bool

Returns whether the geometry is of a collection type (including multi-types).

+		Immutable
st_isempty(geometry: geometry) → bool

Returns whether the geometry is empty.

+		Immutable
st_ispolygonccw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are considered counter-clockwise.

+		Immutable
st_ispolygoncw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are considered clockwise.

+		Immutable
st_isring(geometry: geometry) → bool

Returns whether the geometry is a single linestring that is closed and simple, as defined by ST_IsClosed and ST_IsSimple.

+

This function utilizes the GEOS module.

+		Immutable
st_issimple(geometry: geometry) → bool

Returns true if the geometry has no anomalous geometric points, e.g. that it intersects with or lies tangent to itself.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry) → bool

Returns whether the geometry is valid as defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry, flags: int) → bool

Returns whether the geometry is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry) → string

Returns a string containing the reason the geometry is invalid along with the point of interest, or “Valid Geometry” if it is valid. Validity is defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry, flags: int) → string

Returns the reason the geometry is invalid or “Valid Geometry” if it is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidtrajectory(geometry: geometry) → bool

Returns whether the geometry encodes a valid trajectory.

+

Note the geometry must be a LineString with M coordinates.

+		Immutable
st_length(geography: geography) → float

Returns the length of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geography: geography, use_spheroid: bool) → float

Returns the length of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_length(geometry_str: string) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_length2d(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_linecrossingdirection(linestring_a: geometry, linestring_b: geometry) → int

Returns an interger value defining behavior of crossing of lines: +0: lines do not cross, +-1: linestring_b crosses linestring_a from right to left, +1: linestring_b crosses linestring_a from left to right, +-2: linestring_b crosses linestring_a multiple times from right to left, +2: linestring_b crosses linestring_a multiple times from left to right, +-3: linestring_b crosses linestring_a multiple times from left to left, +3: linestring_b crosses linestring_a multiple times from right to right.

+

Note that the top vertex of the segment touching another line does not count as a crossing, but the bottom vertex of segment touching another line is considered a crossing.

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string) → geometry

Creates a LineString from an Encoded Polyline string.

+

Returns valid results only if the polyline was encoded with 5 decimal places.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string, precision: int4) → geometry

Creates a LineString from an Encoded Polyline string.

+

Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefrommultipoint(geometry: geometry) → geometry

Creates a LineString from a MultiPoint geometry.

+		Immutable
st_linefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_lineinterpolatepoint(geometry: geometry, fraction: float) → geometry

Returns a point along the given LineString which is at given fraction of LineString’s total length.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float, repeat: bool) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length. If repeat is false (default true) then it returns first point.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_linelocatepoint(line: geometry, point: geometry) → float

Returns a float between 0 and 1 representing the location of the closest point on LineString to the given Point, as a fraction of total 2d line length.

+		Immutable
st_linemerge(geometry: geometry) → geometry

Returns a LineString or MultiLineString by joining together constituents of a MultiLineString with matching endpoints. If the input is not a MultiLineString or LineString, an empty GeometryCollection is returned.

+

This function utilizes the GEOS module.

+		Immutable
st_linestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: decimal, end_fraction: decimal) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: float, end_fraction: float) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_longestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the max distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the maximum distance between the geometry’s vertexes. The function will return the longest line that was discovered first when comparing maximum distances if more than one is found.

+		Immutable
st_m(geometry: geometry) → float

Returns the M coordinate of a geometry if it is a Point.

+		Immutable
st_makebox2d(geometry_a: geometry, geometry_b: geometry) → box2d

Creates a box2d from two points. Errors if arguments are not two non-empty points.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with SRID 0.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float, srid: int) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with the given SRID.

+		Immutable
st_makepoint(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float) → geometry

Returns a new Point with the given X, Y, and Z coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float, m: float) → geometry

Returns a new Point with the given X, Y, Z, and M coordinates.

+		Immutable
st_makepointm(x: float, y: float, m: float) → geometry

Returns a new Point with the given X, Y, and M coordinates.

+		Immutable
st_makepolygon(geometry: geometry) → geometry

Returns a new Polygon with the given outer LineString.

+		Immutable
st_makepolygon(outer: geometry, interior: anyelement[]) → geometry

Returns a new Polygon with the given outer LineString and interior (hole) LineString(s).

+		Immutable
st_makevalid(geometry: geometry) → geometry

Returns a valid form of the given geometry according to the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_maxdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the maximum distance across every pair of points comprising the given geometries. Note if the geometries are the same, it will return the maximum distance between the geometry’s vertexes.

+		Immutable
st_memsize(geometry: geometry) → int

Returns the amount of memory space (in bytes) the geometry takes.

+		Immutable
st_minimumboundingcircle(geometry: geometry) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingcircle(geometry: geometry, num_segs: int) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingradius(geometry: geometry) → tuple{geometry AS center, float AS radius}

Returns a record containing the center point and radius of the smallest circle that can fully contains the given geometry.

+		Immutable
st_minimumclearance(geometry: geometry) → float

Returns the minimum distance a vertex can move before producing an invalid geometry. Returns Infinity if no minimum clearance can be found (e.g. for a single point).

+		Immutable
st_minimumclearanceline(geometry: geometry) → geometry

Returns a LINESTRING spanning the minimum distance a vertex can move before producing an invalid geometry. If no minimum clearance can be found (e.g. for a single point), an empty LINESTRING is returned.

+		Immutable
st_mlinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mlinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mpointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multi(geometry: geometry) → geometry

Returns the geometry as a new multi-geometry, e.g converts a POINT to a MULTIPOINT. If the input is already a multitype or collection, it is returned as is.

+		Immutable
st_multilinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multipointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_ndims(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_node(geometry: geometry) → geometry

Adds a node on a geometry for each intersection. Resulting geometry is always a MultiLineString.

+		Immutable
st_normalize(geometry: geometry) → geometry

Returns the geometry in its normalized form.

+

This function utilizes the GEOS module.

+		Immutable
st_npoints(geometry: geometry) → int

Returns the number of points in a given Geometry. Works for any shape type.

+		Immutable
st_nrings(geometry: geometry) → int

Returns the number of rings in a Polygon Geometry. Returns 0 if the shape is not a Polygon.

+		Immutable
st_numgeometries(geometry: geometry) → int

Returns the number of shapes inside a given Geometry.

+		Immutable
st_numinteriorring(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numinteriorrings(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numpoints(geometry: geometry) → int

Returns the number of points in a LineString. Returns NULL if the Geometry is not a LineString.

+		Immutable
st_orderingequals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is exactly equal to geometry_b, having all coordinates in the same order, as well as the same type, SRID, bounding box, and so on.

+		Immutable
st_orientedenvelope(geometry: geometry) → geometry

Returns a minimum rotated rectangle enclosing a geometry. +Note that more than one minimum rotated rectangle may exist. +May return a Point or LineString in the case of degenerate inputs.

+		Immutable
st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_perimeter(geography: geography) → float

Returns the perimeter of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geography: geography, use_spheroid: bool) → float

Returns the perimeter of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_perimeter2d(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_point(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_pointfromgeohash(geohash: string) → geometry

Return a POINT Geometry from a GeoHash string with max precision.

+		Immutable
st_pointfromgeohash(geohash: string, precision: int) → geometry

Return a POINT Geometry from a GeoHash string with supplied precision.

+		Immutable
st_pointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Point, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_pointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointinsidecircle(geometry: geometry, x_coord: float, y_coord: float, radius: float) → bool

Returns the true if the geometry is a point and is inside the circle. Returns false otherwise.

+		Immutable
st_pointn(geometry: geometry, n: int) → geometry

Returns the n-th Point of a LineString (1-indexed). Returns NULL if out of bounds or not a LineString.

+		Immutable
st_pointonsurface(geometry: geometry) → geometry

Returns a point that intersects with the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_points(geometry: geometry) → geometry

Returns all coordinates in the given Geometry as a MultiPoint, including duplicates.

+		Immutable
st_polyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygon(geometry: geometry, srid: int) → geometry

Returns a new Polygon from the given LineString and sets its SRID. It is equivalent to ST_MakePolygon with a single argument followed by ST_SetSRID.

+		Immutable
st_polygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_project(geography: geography, distance: float, azimuth: float) → geography

Returns a point projected from a start point along a geodesic using a given distance and azimuth (bearing). +This is known as the direct geodesic problem.

+

The distance is given in meters. Negative values are supported.

+

The azimuth (also known as heading or bearing) is given in radians. It is measured clockwise from true north (azimuth zero). +East is azimuth π/2 (90 degrees); south is azimuth π (180 degrees); west is azimuth 3π/2 (270 degrees). +Negative azimuth values and values greater than 2π (360 degrees) are supported.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, bnr: int) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b using the given boundary node rule (1:OGC/MOD2, 2:Endpoint, 3:MultivalentEndpoint, 4:MonovalentEndpoint).

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, pattern: string) → bool

Returns whether the DE-9IM spatial relation between geometry_a and geometry_b matches the DE-9IM pattern.

+

This function utilizes the GEOS module.

+		Immutable
st_relatematch(intersection_matrix: string, pattern: string) → bool

Returns whether the given DE-9IM intersection matrix satisfies the given pattern.

+		Immutable
st_removepoint(line_string: geometry, index: int) → geometry

Removes the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_removerepeatedpoints(geometry: geometry) → geometry

Returns a geometry with repeated points removed.

+		Immutable
st_removerepeatedpoints(geometry: geometry, tolerance: float) → geometry

Returns a geometry with repeated points removed, within the given distance tolerance.

+		Immutable
st_reverse(geometry: geometry) → geometry

Returns a modified geometry by reversing the order of its vertices.

+		Immutable
st_rotate(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_point: geometry) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_x: float, origin_y: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotatex(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the x axis by a rotation angle.

+		Immutable
st_rotatey(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the y axis by a rotation angle.

+		Immutable
st_rotatez(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the z axis by a rotation angle.

+		Immutable
st_s2covering(geography: geography) → geography

Returns a geography which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geography: geography, settings: string) → geography

Returns a geography which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geography, 's2_max_level=15,s2_level_mod=3').

+		Immutable
st_s2covering(geometry: geometry) → geometry

Returns a geometry which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geometry: geometry, settings: string) → geometry

Returns a geometry which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geometry, 's2_max_level=15,s2_level_mod=3')

+		Immutable
st_scale(g: geometry, factor: geometry) → geometry

Returns a modified Geometry scaled by taking in a Geometry as the factor.

+		Immutable
st_scale(g: geometry, factor: geometry, origin: geometry) → geometry

Returns a modified Geometry scaled by the Geometry factor relative to a false origin.

+		Immutable
st_scale(geometry: geometry, x_factor: float, y_factor: float) → geometry

Returns a modified Geometry scaled by the given factors.

+		Immutable
st_segmentize(geography: geography, max_segment_length_meters: float) → geography

Returns a modified Geography having no segment longer than the given max_segment_length meters.

+

The calculations are done on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_segmentize(geometry: geometry, max_segment_length: float) → geometry

Returns a modified Geometry having no segment longer than the given max_segment_length. Length units are in units of spatial reference.

+		Immutable
st_setpoint(line_string: geometry, index: int, point: geometry) → geometry

Sets the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_setsrid(geography: geography, srid: int) → geography

Sets a Geography to a new SRID without transforming the coordinates.

+		Immutable
st_setsrid(geometry: geometry, srid: int) → geometry

Sets a Geometry to a new SRID without transforming the coordinates.

+		Immutable
st_sharedpaths(geometry_a: geometry, geometry_b: geometry) → geometry

Returns a collection containing paths shared by the two input geometries.

+

Those going in the same direction are in the first element of the collection, +those going in the opposite direction are in the second element. +The paths themselves are given in the direction of the first geometry.

+		Immutable
st_shiftlongitude(geometry: geometry) → geometry

Returns a modified version of a geometry in which the longitude (X coordinate) of each point is incremented by 360 if it is <0 and decremented by 360 if it is >180. The result is only meaningful if the coordinates are in longitude/latitude.

+		Immutable
st_shortestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the minimum distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the minimum distance between the geometry’s vertexes. The function will return the shortest line that was discovered first when comparing minimum distances if more than one is found.

+		Immutable
st_simplify(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm.

+

This function utilizes the GEOS module.

+		Immutable
st_simplify(geometry: geometry, tolerance: float, preserve_collapsed: bool) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, retaining objects that would be too small given the tolerance if preserve_collapsed is set to true.

+		Immutable
st_simplifypreservetopology(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, avoiding the creation of invalid geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_snap(input: geometry, target: geometry, tolerance: float) → geometry

Snaps the vertices and segments of input geometry the target geometry’s vertices. +Tolerance is used to control where snapping is performed. The result geometry is the input geometry with the vertices snapped. +If no snapping occurs then the input geometry is returned unchanged.

+		Immutable
st_snaptogrid(geometry: geometry, origin: geometry, size_x: float, size_y: float, size_z: float, size_m: float) → geometry

Snap a geometry to a grid defined by the given origin and X, Y, Z, and M cell sizes. Any dimension with a 0 cell size will not be snapped.

+		Immutable
st_snaptogrid(geometry: geometry, origin_x: float, origin_y: float, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y based on an origin of (origin_x, origin_y).

+		Immutable
st_snaptogrid(geometry: geometry, size: float) → geometry

Snap a geometry to a grid of the given size. The specified size is only used to snap X and Y coordinates.

+		Immutable
st_snaptogrid(geometry: geometry, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y.

+		Immutable
st_srid(geography: geography) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geography as defined in spatial_ref_sys table.

+		Immutable
st_srid(geometry: geometry) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geometry as defined in spatial_ref_sys table.

+		Immutable
st_startpoint(geometry: geometry) → geometry

Returns the first point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_subdivide(geometry: geometry) → geometry

Returns a geometry divided into parts, where each part contains no more than 256 vertices.

+		Immutable
st_subdivide(geometry: geometry, max_vertices: int4) → geometry

Returns a geometry divided into parts, where each part contains no more than the number of vertices provided.

+		Immutable
st_summary(geography: geography) → string

Returns a text summary of the contents of the geography.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_summary(geometry: geometry) → string

Returns a text summary of the contents of the geometry.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_swapordinates(geometry: geometry, swap_ordinate_string: string) → geometry

Returns a version of the given geometry with given ordinates swapped. +The swap_ordinate_string parameter is a 2-character string naming the ordinates to swap. Valid names are: x, y, z and m.

+		Immutable
st_symdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_symmetricdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4, bounds: geometry) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4, bounds: geometry, margin: float) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, srid: int) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates. The supplied SRID is set on the new geometry.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, srid: int) → geometry

Transforms a geometry into the given SRID coordinate reference system by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system referenced by the projection text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float, delta_z: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_transscale(geometry: geometry, delta_x: float, delta_y: float, x_factor: float, y_factor: float) → geometry

Translates the geometry using the deltaX and deltaY args, then scales it using the XFactor, YFactor args, working in 2D only.

+		Immutable
st_unaryunion(geometry: geometry) → geometry

Returns a union of the components for any geometry or geometry collection provided. Dissolves boundaries of a multipolygon.

+		Immutable
st_voronoilines(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoipolygons(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_wkbtosql(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_wkttosql(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_x(geometry: geometry) → float

Returns the X coordinate of a geometry if it is a Point.

+		Immutable
st_xmax(box2d: box2d) → float

Returns the maximum X ordinate of a box2d.

+		Immutable
st_xmax(geometry: geometry) → float

Returns the maximum X ordinate of a geometry.

+		Immutable
st_xmin(box2d: box2d) → float

Returns the minimum X ordinate of a box2d.

+		Immutable
st_xmin(geometry: geometry) → float

Returns the minimum X ordinate of a geometry.

+		Immutable
st_y(geometry: geometry) → float

Returns the Y coordinate of a geometry if it is a Point.

+		Immutable
st_ymax(box2d: box2d) → float

Returns the maximum Y ordinate of a box2d.

+		Immutable
st_ymax(geometry: geometry) → float

Returns the maximum Y ordinate of a geometry.

+		Immutable
st_ymin(box2d: box2d) → float

Returns the minimum Y ordinate of a box2d.

+		Immutable
st_ymin(geometry: geometry) → float

Returns the minimum Y ordinate of a geometry.

+		Immutable
st_z(geometry: geometry) → float

Returns the Z coordinate of a geometry if it is a Point.

+		Immutable
st_zmflag(geometry: geometry) → int2

Returns a code based on the ZM coordinate dimension of a geometry (XY = 0, XYM = 1, XYZ = 2, XYZM = 3).

+		Immutable
+ +### String and byte functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ascii(val: string) → int

Returns the character code of the first character in val. Despite the name, the function supports Unicode too.

+		Immutable
bit_count(val: bytes) → int

Calculates the number of bits set used to represent val.

+		Immutable
bit_count(val: varbit) → int

Calculates the number of bits set used to represent val.

+		Immutable
bit_length(val: bytes) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: string) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
bitmask_and(a: string, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: string, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
btrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning or end of input (applies recursively).

+

For example, btrim('doggie', 'eod') returns ggi.

+		Immutable
btrim(val: string) → string

Removes all spaces from the beginning and end of val.

+		Immutable
char_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
char_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
character_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
character_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
chr(val: int) → string

Returns the character with the code given in val. Inverse function of ascii().

+		Immutable
compress(data: bytes, codec: string) → bytes

Compress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
concat(string...) → string

Concatenates a comma-separated list of strings.

+		Immutable
concat_ws(string...) → string

Uses the first argument as a separator between the concatenation of the subsequent arguments.

+

For example concat_ws('!','wow','great') returns wow!great.

+		Immutable
convert_from(str: bytes, enc: string) → string

Decode the bytes in str into a string using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
convert_to(str: string, enc: string) → bytes

Encode the string str as a byte array using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
decode(text: string, format: string) → bytes

Decodes data using format (hex / escape / base64).

+		Immutable
decompress(data: bytes, codec: string) → bytes

Decompress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
difference(source: string, target: string) → int

Convert two strings to their Soundex codes and report the number of matching code positions.

+		Immutable
encode(data: bytes, format: string) → string

Encodes data using format (hex / escape / base64).

+		Immutable
format(string, anyelement...) → string

Interprets the first argument as a format string similar to C sprintf and interpolates the remaining arguments.

+		Stable
from_ip(val: bytes) → string

Converts the byte string representation of an IP to its character string representation.

+		Immutable
from_uuid(val: bytes) → string

Converts the byte string representation of a UUID to its character string representation.

+		Immutable
get_bit(bit_string: varbit, index: int) → int

Extracts a bit at given index in the bit array.

+		Immutable
get_bit(byte_string: bytes, index: int) → int

Extracts a bit at the given index in the byte array.

+		Immutable
get_byte(byte_string: bytes, index: int) → int

Extracts a byte at the given index in the byte array.

+		Immutable
initcap(val: string) → string

Capitalizes the first letter of val.

+		Immutable
left(input: bytes, return_set: int) → bytes

Returns the first return_set bytes from input.

+		Immutable
left(input: string, return_set: int) → string

Returns the first return_set characters from input.

+		Immutable
length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
length(val: string) → int

Calculates the number of characters in val.

+		Immutable
length(val: varbit) → int

Calculates the number of bits in val.

+		Immutable
lower(val: string) → string

Converts all characters in val to their lower-case equivalents.

+		Immutable
lpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the left of string.If string is longer than length it is truncated.

+		Immutable
lpad(string: string, length: int, fill: string) → string

Pads string by adding fill to the left of string to make it length. If string is longer than length it is truncated.

+		Immutable
ltrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning (left-hand side) of input (applies recursively).

+

For example, ltrim('doggie', 'od') returns ggie.

+		Immutable
ltrim(val: string) → string

Removes all spaces from the beginning (left-hand side) of val.

+		Immutable
md5(bytes...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
md5(string...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
octet_length(val: bytes) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: string) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int) → string

Replaces characters in input with overlay_val starting at start_pos (begins at 1).

+

For example, overlay('doggie', 'CAT', 2) returns dCATie.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int, end_pos: int) → string

Deletes the characters in input between start_pos and end_pos (count starts at 1), and then insert overlay_val at start_pos.

+		Immutable
parse_date(string: string, datestyle: string) → date

Parses a date assuming it is in format specified by DateStyle.

+		Immutable
parse_date(val: string) → date

Parses a date assuming it is in MDY format.

+		Immutable
parse_ident(qualified_identifier: string) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. Extra characters after the last identifier are considered an error

+		Immutable
parse_ident(qualified_identifier: string, strict: bool) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. If strict is false, then extra characters after the last identifier are ignored.

+		Immutable
parse_interval(string: string, style: string) → interval

Convert a string to an interval using the given IntervalStyle.

+		Immutable
parse_interval(val: string) → interval

Convert a string to an interval assuming the Postgres IntervalStyle.

+		Immutable
parse_time(string: string, timestyle: string) → time

Parses a time assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_time(val: string) → time

Parses a time assuming the date (if any) is in MDY format.

+		Immutable
parse_timestamp(string: string, datestyle: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates formatted using the given DateStyle.

+		Immutable
parse_timestamp(val: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates are in MDY format.

+		Immutable
parse_timetz(string: string, timestyle: string) → timetz

Parses a timetz assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_timetz(val: string) → timetz

Parses a timetz assuming the date (if any) is in MDY format.

+		Immutable
prettify_statement(statement: string, line_width: int, align_mode: int, case_mode: int) → string

Prettifies a statement using a user-configured pretty-printing config. +Align mode values range from 0 - 3, representing no, partial, full, and extra alignment respectively. +Case mode values range between 0 - 1, representing lower casing and upper casing respectively.

+		Immutable
prettify_statement(val: string) → string

Prettifies a statement using a the default pretty-printing config.

+		Immutable
quote_ident(val: string) → string

Return val suitably quoted to serve as identifier in a SQL statement.

+		Immutable
quote_literal(val: string) → string

Return val suitably quoted to serve as string literal in a SQL statement.

+		Immutable
quote_literal(val: anyelement) → string

Coerce val to a string and then quote it as a literal.

+		Stable
quote_nullable(val: string) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Immutable
quote_nullable(val: anyelement) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Stable
regexp_extract(input: string, regex: string) → string

Returns the first match for the Regular Expression regex in input.

+		Immutable
regexp_replace(input: string, regex: string, replace: string) → string

Replaces matches for the Regular Expression regex in input with the Regular Expression replace.

+		Immutable
regexp_replace(input: string, regex: string, replace: string, flags: string) → string

Replaces matches for the regular expression regex in input with the regular expression replace using flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
repeat(input: string, repeat_counter: int) → string

Concatenates input repeat_counter number of times.

+

For example, repeat('dog', 2) returns dogdog.

+		Immutable
replace(input: string, find: string, replace: string) → string

Replaces all occurrences of find with replace in input

+		Immutable
reverse(val: string) → string

Reverses the order of the string’s characters.

+		Immutable
right(input: bytes, return_set: int) → bytes

Returns the last return_set bytes from input.

+		Immutable
right(input: string, return_set: int) → string

Returns the last return_set characters from input.

+		Immutable
rpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the right of string. If string is longer than length it is truncated.

+		Immutable
rpad(string: string, length: int, fill: string) → string

Pads string to length by adding fill to the right of string. If string is longer than length it is truncated.

+		Immutable
rtrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the end (right-hand side) of input (applies recursively).

+

For example, rtrim('doggie', 'ei') returns dogg.

+		Immutable
rtrim(val: string) → string

Removes all spaces from the end (right-hand side) of val.

+		Immutable
set_bit(bit_string: varbit, index: int, to_set: int) → varbit

Updates a bit at given index in the bit array.

+		Immutable
set_bit(byte_string: bytes, index: int, to_set: int) → bytes

Updates a bit at the given index in the byte array.

+		Immutable
set_byte(byte_string: bytes, index: int, to_set: int) → bytes

Updates a byte at the given index in the byte array.

+		Immutable
sha1(bytes...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha1(string...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha224(bytes...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha224(string...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha256(bytes...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha256(string...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha384(bytes...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha384(string...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha512(bytes...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
sha512(string...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
similar_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_to_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
split_part(input: string, delimiter: string, return_index_pos: int) → string

Splits input on delimiter and return the value in the return_index_pos position (starting at 1).

+

For example, split_part('123.456.789.0','.',3)returns 789.

+		Immutable
strpos(input: bytes, find: bytes) → int

Calculates the position where the byte subarray find begins in input.

+		Immutable
strpos(input: string, find: string) → int

Calculates the position where the string find begins in input.

+

For example, strpos('doggie', 'gie') returns 4.

+		Immutable
strpos(input: varbit, find: varbit) → int

Calculates the position where the bit subarray find begins in input.

+		Immutable
substr(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substr(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substr(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substring(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substring(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
to_char_with_style(date: date, datestyle: string) → string

Convert an date to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_char_with_style(interval: interval, style: string) → string

Convert an interval to a string using the given IntervalStyle.

+		Immutable
to_char_with_style(timestamp: timestamp, datestyle: string) → string

Convert an timestamp to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_english(val: int) → string

This function enunciates the value of its argument using English cardinals.

+		Immutable
to_hex(val: bytes) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: int) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: string) → string

Converts val to its hexadecimal representation.

+		Immutable
to_ip(val: string) → bytes

Converts the character string representation of an IP to its byte string representation.

+		Immutable
to_uuid(val: string) → bytes

Converts the character string representation of a UUID to its byte string representation.

+		Immutable
translate(input: string, find: string, replace: string) → string

In input, replaces the first character from find with the first character in replace; repeat for each character in find.

+

For example, translate('doggie', 'dog', '123'); returns 1233ie.

+		Immutable
ulid_to_uuid(val: string) → uuid

Converts a ULID string to its UUID-encoded representation.

+		Immutable
unaccent(val: string) → string

Removes accents (diacritic signs) from the text provided in val.

+		Immutable
upper(val: string) → string

Converts all characters in val to their to their upper-case equivalents.

+		Immutable
+ +### System info functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cluster_logical_timestamp() → decimal

Returns the logical time of the current transaction as +a CockroachDB HLC in decimal form.

+

Note that uses of this function disable server-side optimizations and +may increase either contention or retry errors, or both.

+

Returns an error if run in a transaction with an isolation level weaker than SERIALIZABLE.

+		Volatile
current_database() → string

Returns the current database.

+		Stable
current_schema() → string

Returns the current schema.

+		Stable
current_schemas(include_pg_catalog: bool) → string[]

Returns the valid schemas in the search path.

+		Stable
current_user() → string

Returns the current user. This function is provided for compatibility with PostgreSQL.

+		Stable
session_user() → string

Returns the session user. This function is provided for compatibility with PostgreSQL.

+		Stable
to_regclass(text: string) → regtype

Translates a textual relation name to its OID

+		Stable
to_regnamespace(text: string) → regtype

Translates a textual schema name to its OID

+		Stable
to_regproc(text: string) → regtype

Translates a textual function or procedure name to its OID

+		Stable
to_regprocedure(text: string) → regtype

Translates a textual function or procedure name(with argument types) to its OID

+		Stable
to_regrole(text: string) → regtype

Translates a textual role name to its OID

+		Stable
to_regtype(text: string) → regtype

Translates a textual type name to its OID

+		Stable
version() → string

Returns the node’s version of CockroachDB.

+		Volatile
+ +### TIMETZ functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
current_time() → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time() → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_time(precision: int) → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time(precision: int) → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → timetz

Returns the current transaction’s time with time zone.

+		Stable
localtime(precision: int) → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime(precision: int) → timetz

Returns the current transaction’s time with time zone.

+		Stable
+ +### Trigrams functions + + + + + + +
Function → ReturnsDescriptionVolatility
show_trgm(input: string) → string[]

Returns an array of all the trigrams in the given string.

+		Immutable
similarity(left: string, right: string) → float

Returns a number that indicates how similar the two arguments are. The range of the result is zero (indicating that the two strings are completely dissimilar) to one (indicating that the two strings are identical).

+		Immutable
+ +### UUID functions + + + + + +
Function → ReturnsDescriptionVolatility
uuid_to_ulid(val: uuid) → string

Converts a UUID-encoded ULID to its string representation.

+		Immutable
+ +### Compatibility functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
col_description(table_oid: oid, column_number: int) → string

Returns the comment for a table column, which is specified by the OID of its table and its column number. (obj_description cannot be used for table columns, since columns do not have OIDs of their own.)

+		Stable
current_setting(setting_name: string) → string

System info

+		Stable
current_setting(setting_name: string, missing_ok: bool) → string

System info

+		Stable
format_type(type_oid: oid, typemod: int) → string

Returns the SQL name of a data type that is identified by its type OID and possibly a type modifier. Currently, the type modifier is ignored.

+		Stable
getdatabaseencoding() → string

Returns the current encoding name used by the database.

+		Stable
has_any_column_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_column_privilege(table: string, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: string, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_database_privilege(database: string, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(database: oid, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(user: string, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: string, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_foreign_data_wrapper_privilege(fdw: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(fdw: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_function_privilege(function: string, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(function: oid, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(user: string, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: string, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_language_privilege(language: string, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(language: oid, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(user: string, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: string, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_schema_privilege(schema: string, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(schema: oid, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_sequence_privilege(sequence: string, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(sequence: oid, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_server_privilege(server: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(server: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_table_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_tablespace_privilege(tablespace: string, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(tablespace: oid, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_type_privilege(type: string, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(type: oid, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(user: string, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: string, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
information_schema._pg_numeric_precision(typid: oid, typmod: int4) → int

Returns the precision of the given type with type modifier

+		Immutable
information_schema._pg_numeric_precision_radix(typid: oid, typmod: int4) → int

Returns the radix of the given type with type modifier

+		Immutable
information_schema._pg_numeric_scale(typid: oid, typmod: int4) → int

Returns the scale of the given type with type modifier

+		Immutable
nameconcatoid(name: string, oid: oid) → name

Used in the information_schema to produce specific_name columns, which are supposed to be unique per schema. The result is the same as ($1::text || ‘_’ || $2::text)::name except that, if it would not fit in 63 characters, we make it do so by truncating the name input (not the oid).

+		Immutable
obj_description(object_oid: oid) → string

Returns the comment for a database object specified by its OID alone. This is deprecated since there is no guarantee that OIDs are unique across different system catalogs; therefore, the wrong comment might be returned.

+		Stable
obj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a database object specified by its OID and the name of the containing system catalog. For example, obj_description(123456, ‘pg_class’) would retrieve the comment for the table with OID 123456.

+		Stable
oidvectortypes(vector: oidvector) → string

Generates a comma seperated string of type names from an oidvector.

+		Stable
pg_backend_pid() → int

Returns a numerical ID attached to this session. This ID is part of the query cancellation key used by the wire protocol. This function was only added for compatibility, and unlike in Postgres, the returned value does not correspond to a real process ID.

+		Stable
pg_collation_for(str: anyelement) → string

Returns the collation of the argument

+		Stable
pg_column_is_updatable(reloid: oid, attnum: int2, include_triggers: bool) → bool

Returns whether the given column can be updated.

+		Stable
pg_column_size(anyelement...) → int

Return size in bytes of the column provided as an argument

+		Immutable
pg_function_is_visible(oid: oid) → bool

Returns whether the function with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_get_function_arg_default(func_oid: oid, arg_num: int4) → string

Get textual representation of a function argument’s default value. The second argument of this function is the argument number among all arguments (i.e. proallargtypes, not proargtypes), starting with 1, because that’s how information_schema.sql uses it. Currently, this always returns NULL, since CockroachDB does not support default values.

+		Stable
pg_get_function_arguments(func_oid: oid) → string

Returns the argument list (with defaults) necessary to identify a function, in the form it would need to appear in within CREATE FUNCTION.

+		Stable
pg_get_function_identity_arguments(func_oid: oid) → string

Returns the argument list (without defaults) necessary to identify a function, in the form it would need to appear in within ALTER FUNCTION, for instance.

+		Stable
pg_get_function_result(func_oid: oid) → string

Returns the types of the result of the specified function.

+		Stable
pg_get_functiondef(func_oid: oid) → string

For user-defined functions, returns the definition of the specified function. For builtin functions, returns the name of the function.

+		Stable
pg_get_indexdef(index_oid: oid) → string

Gets the CREATE INDEX command for index

+		Stable
pg_get_indexdef(index_oid: oid, column_no: int, pretty_bool: bool) → string

Gets the CREATE INDEX command for index, or definition of just one index column when given a non-zero column number

+		Stable
pg_get_serial_sequence(table_name: string, column_name: string) → string

Returns the name of the sequence used by the given column_name in the table table_name.

+		Stable
pg_get_viewdef(view_oid: oid) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_get_viewdef(view_oid: oid, pretty_bool: bool) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_has_role(role: string, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(role: oid, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(user: string, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: string, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_is_other_temp_schema(oid: oid) → bool

Returns true if the given OID is the OID of another session’s temporary schema. (This can be useful, for example, to exclude other sessions’ temporary tables from a catalog display.)

+		Stable
pg_my_temp_schema() → oid

Returns the OID of the current session’s temporary schema, or zero if it has none (because it has not created any temporary tables).

+		Stable
pg_relation_is_updatable(reloid: oid, include_triggers: bool) → int4

Returns the update events the relation supports.

+		Stable
pg_sequence_last_value(sequence_oid: oid) → int

Returns the last value generated by a sequence, or NULL if the sequence has not been used yet.

+		Volatile
pg_sleep(seconds: float) → bool

pg_sleep makes the current session’s process sleep until seconds seconds have elapsed. seconds is a value of type double precision, so fractional-second delays can be specified.

+		Volatile
pg_table_is_visible(oid: oid) → bool

Returns whether the table with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_type_is_visible(oid: oid) → bool

Returns whether the type with the given OID belongs to one of the schemas on the search path.

+		Stable
set_config(setting_name: string, new_value: string, is_local: bool) → string

System info

+		Volatile
shobj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a shared database object specified by its OID and the name of the containing system catalog. This is just like obj_description except that it is used for retrieving comments on shared objects (e.g. databases).

+		Stable
+ diff --git a/src/current/_includes/cockroach-generated/release-24.1/sql/operators.md b/src/current/_includes/cockroach-generated/release-24.1/sql/operators.md new file mode 100644 index 00000000000..dde5d133a6c --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.1/sql/operators.md @@ -0,0 +1,635 @@ + + + + + +
#Return
int # intint
varbit # varbitvarbit
+ + + + +
#>Return
jsonb #> string[]jsonb
+ + + + +
#>>Return
jsonb #>> string[]string
+ + + + + + + + + +
%Return
decimal % decimaldecimal
decimal % intdecimal
float % floatfloat
int % decimaldecimal
int % intint
string % stringbool
+ + + + + + +
&Return
inet & inetinet
int & intint
varbit & varbitvarbit
+ + + + + + + + + +
&&Return
anyelement && anyelementbool
box2d && box2dbool
box2d && geometrybool
geometry && box2dbool
geometry && geometrybool
inet && inetbool
+ + + + + + + + + + + + + + +
*Return
decimal * decimaldecimal
decimal * intdecimal
decimal * intervalinterval
float * floatfloat
float * intervalinterval
int * decimaldecimal
int * intint
int * intervalinterval
interval * decimalinterval
interval * floatinterval
interval * intinterval
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Return
+decimaldecimal
+floatfloat
+intint
+intervalinterval
date + intdate
date + intervaltimestamp
date + timetimestamp
date + timetztimestamptz
decimal + decimaldecimal
decimal + intdecimal
decimal + pg_lsnpg_lsn
float + floatfloat
inet + intinet
int + datedate
int + decimaldecimal
int + inetinet
int + intint
interval + datetimestamp
interval + intervalinterval
interval + timetime
interval + timestamptimestamp
interval + timestamptztimestamptz
interval + timetztimetz
pg_lsn + decimalpg_lsn
time + datetimestamp
time + intervaltime
timestamp + intervaltimestamp
timestamptz + intervaltimestamptz
timetz + datetimestamptz
timetz + intervaltimetz
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
-Return
-decimaldecimal
-floatfloat
-intint
-intervalinterval
date - dateint
date - intdate
date - intervaltimestamp
date - timetimestamp
decimal - decimaldecimal
decimal - intdecimal
float - floatfloat
inet - inetint
inet - intinet
int - decimaldecimal
int - intint
interval - intervalinterval
jsonb - intjsonb
jsonb - stringjsonb
jsonb - string[]jsonb
pg_lsn - decimalpg_lsn
pg_lsn - pg_lsndecimal
time - intervaltime
time - timeinterval
timestamp - intervaltimestamp
timestamp - timestampinterval
timestamp - timestamptzinterval
timestamptz - intervaltimestamptz
timestamptz - timestampinterval
timestamptz - timestamptzinterval
timetz - intervaltimetz
+ + + + + +
->Return
jsonb -> intjsonb
jsonb -> stringjsonb
+ + + + + +
->>Return
jsonb ->> intstring
jsonb ->> stringstring
+ + + + + + + + + + +
/Return
decimal / decimaldecimal
decimal / intdecimal
float / floatfloat
int / decimaldecimal
int / intdecimal
interval / floatinterval
interval / intinterval
+ + + + + + + + +
//Return
decimal // decimaldecimal
decimal // intdecimal
float // floatfloat
int // decimaldecimal
int // intint
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<Return
anyenum < anyenumbool
bool < boolbool
bool[] < bool[]bool
box2d < box2dbool
bpchar < bpcharbool
bytes < bytesbool
bytes[] < bytes[]bool
collatedstring < collatedstringbool
date < datebool
date < timestampbool
date < timestamptzbool
date[] < date[]bool
decimal < decimalbool
decimal < floatbool
decimal < intbool
decimal[] < decimal[]bool
float < decimalbool
float < floatbool
float < intbool
float[] < float[]bool
geography < geographybool
geometry < geometrybool
inet < inetbool
inet[] < inet[]bool
int < decimalbool
int < floatbool
int < intbool
int < oidbool
int[] < int[]bool
interval < intervalbool
interval[] < interval[]bool
jsonb < jsonbbool
oid < intbool
oid < oidbool
pg_lsn < pg_lsnbool
refcursor < refcursorbool
string < stringbool
string[] < string[]bool
time < timebool
time < timetzbool
time[] < time[]bool
timestamp < datebool
timestamp < timestampbool
timestamp < timestamptzbool
timestamp[] < timestamp[]bool
timestamptz < datebool
timestamptz < timestampbool
timestamptz < timestamptzbool
timestamptz < timestamptzbool
timetz < timebool
timetz < timetzbool
tuple < tuplebool
uuid < uuidbool
uuid[] < uuid[]bool
varbit < varbitbool
+ + + + + + +
<<Return
inet << inetbool
int << intint
varbit << intvarbit
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<=Return
anyenum <= anyenumbool
bool <= boolbool
bool[] <= bool[]bool
box2d <= box2dbool
bpchar <= bpcharbool
bytes <= bytesbool
bytes[] <= bytes[]bool
collatedstring <= collatedstringbool
date <= datebool
date <= timestampbool
date <= timestamptzbool
date[] <= date[]bool
decimal <= decimalbool
decimal <= floatbool
decimal <= intbool
decimal[] <= decimal[]bool
float <= decimalbool
float <= floatbool
float <= intbool
float[] <= float[]bool
geography <= geographybool
geometry <= geometrybool
inet <= inetbool
inet[] <= inet[]bool
int <= decimalbool
int <= floatbool
int <= intbool
int <= oidbool
int[] <= int[]bool
interval <= intervalbool
interval[] <= interval[]bool
jsonb <= jsonbbool
oid <= intbool
oid <= oidbool
pg_lsn <= pg_lsnbool
refcursor <= refcursorbool
string <= stringbool
string[] <= string[]bool
time <= timebool
time <= timetzbool
time[] <= time[]bool
timestamp <= datebool
timestamp <= timestampbool
timestamp <= timestamptzbool
timestamp[] <= timestamp[]bool
timestamptz <= datebool
timestamptz <= timestampbool
timestamptz <= timestamptzbool
timestamptz <= timestamptzbool
timetz <= timebool
timetz <= timetzbool
tuple <= tuplebool
uuid <= uuidbool
uuid[] <= uuid[]bool
varbit <= varbitbool
+ + + + + +
<@Return
anyelement <@ anyelementbool
jsonb <@ jsonbbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
=Return
anyenum = anyenumbool
bool = boolbool
bool[] = bool[]bool
box2d = box2dbool
bpchar = bpcharbool
bytes = bytesbool
bytes[] = bytes[]bool
collatedstring = collatedstringbool
date = datebool
date = timestampbool
date = timestamptzbool
date[] = date[]bool
decimal = decimalbool
decimal = floatbool
decimal = intbool
decimal[] = decimal[]bool
float = decimalbool
float = floatbool
float = intbool
float[] = float[]bool
geography = geographybool
geometry = geometrybool
inet = inetbool
inet[] = inet[]bool
int = decimalbool
int = floatbool
int = intbool
int = oidbool
int[] = int[]bool
interval = intervalbool
interval[] = interval[]bool
jsonb = jsonbbool
oid = intbool
oid = oidbool
pg_lsn = pg_lsnbool
refcursor = refcursorbool
string = stringbool
string[] = string[]bool
time = timebool
time = timetzbool
time[] = time[]bool
timestamp = datebool
timestamp = timestampbool
timestamp = timestamptzbool
timestamp[] = timestamp[]bool
timestamptz = datebool
timestamptz = timestampbool
timestamptz = timestamptzbool
timestamptz = timestamptzbool
timetz = timebool
timetz = timetzbool
tsquery = tsquerybool
tsvector = tsvectorbool
tuple = tuplebool
uuid = uuidbool
uuid[] = uuid[]bool
varbit = varbitbool
+ + + + + + +
>>Return
inet >> inetbool
int >> intint
varbit >> intvarbit
+ + + + +
?Return
jsonb ? stringbool
+ + + + +
?&Return
jsonb ?& string[]bool
+ + + + +
?|Return
jsonb ?| string[]bool
+ + + + + +
@>Return
anyelement @> anyelementbool
jsonb @> jsonbbool
+ + + + + +
@@Return
tsquery @@ tsvectorbool
tsvector @@ tsquerybool
+ + + + +
ILIKEReturn
string ILIKE stringbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
INReturn
anyenum IN tuplebool
bool IN tuplebool
box2d IN tuplebool
bpchar IN tuplebool
bytes IN tuplebool
collatedstring IN tuplebool
date IN tuplebool
decimal IN tuplebool
float IN tuplebool
geography IN tuplebool
geometry IN tuplebool
inet IN tuplebool
int IN tuplebool
interval IN tuplebool
jsonb IN tuplebool
oid IN tuplebool
pg_lsn IN tuplebool
refcursor IN tuplebool
string IN tuplebool
time IN tuplebool
timestamp IN tuplebool
timestamptz IN tuplebool
timetz IN tuplebool
tuple IN tuplebool
uuid IN tuplebool
varbit IN tuplebool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IS NOT DISTINCT FROMReturn
anyelement IS NOT DISTINCT FROM unknownbool
anyenum IS NOT DISTINCT FROM anyenumbool
bool IS NOT DISTINCT FROM boolbool
bool[] IS NOT DISTINCT FROM bool[]bool
box2d IS NOT DISTINCT FROM box2dbool
bpchar IS NOT DISTINCT FROM bpcharbool
bytes IS NOT DISTINCT FROM bytesbool
bytes[] IS NOT DISTINCT FROM bytes[]bool
collatedstring IS NOT DISTINCT FROM collatedstringbool
date IS NOT DISTINCT FROM datebool
date IS NOT DISTINCT FROM timestampbool
date IS NOT DISTINCT FROM timestamptzbool
date[] IS NOT DISTINCT FROM date[]bool
decimal IS NOT DISTINCT FROM decimalbool
decimal IS NOT DISTINCT FROM floatbool
decimal IS NOT DISTINCT FROM intbool
decimal[] IS NOT DISTINCT FROM decimal[]bool
float IS NOT DISTINCT FROM decimalbool
float IS NOT DISTINCT FROM floatbool
float IS NOT DISTINCT FROM intbool
float[] IS NOT DISTINCT FROM float[]bool
geography IS NOT DISTINCT FROM geographybool
geometry IS NOT DISTINCT FROM geometrybool
inet IS NOT DISTINCT FROM inetbool
inet[] IS NOT DISTINCT FROM inet[]bool
int IS NOT DISTINCT FROM decimalbool
int IS NOT DISTINCT FROM floatbool
int IS NOT DISTINCT FROM intbool
int IS NOT DISTINCT FROM oidbool
int[] IS NOT DISTINCT FROM int[]bool
interval IS NOT DISTINCT FROM intervalbool
interval[] IS NOT DISTINCT FROM interval[]bool
jsonb IS NOT DISTINCT FROM jsonbbool
oid IS NOT DISTINCT FROM intbool
oid IS NOT DISTINCT FROM oidbool
pg_lsn IS NOT DISTINCT FROM pg_lsnbool
refcursor IS NOT DISTINCT FROM refcursorbool
string IS NOT DISTINCT FROM stringbool
string[] IS NOT DISTINCT FROM string[]bool
time IS NOT DISTINCT FROM timebool
time IS NOT DISTINCT FROM timetzbool
time[] IS NOT DISTINCT FROM time[]bool
timestamp IS NOT DISTINCT FROM datebool
timestamp IS NOT DISTINCT FROM timestampbool
timestamp IS NOT DISTINCT FROM timestamptzbool
timestamp[] IS NOT DISTINCT FROM timestamp[]bool
timestamptz IS NOT DISTINCT FROM datebool
timestamptz IS NOT DISTINCT FROM timestampbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timetz IS NOT DISTINCT FROM timebool
timetz IS NOT DISTINCT FROM timetzbool
tsquery IS NOT DISTINCT FROM tsquerybool
tsvector IS NOT DISTINCT FROM tsvectorbool
tuple IS NOT DISTINCT FROM tuplebool
unknown IS NOT DISTINCT FROM unknownbool
unknown IS NOT DISTINCT FROM voidbool
uuid IS NOT DISTINCT FROM uuidbool
uuid[] IS NOT DISTINCT FROM uuid[]bool
varbit IS NOT DISTINCT FROM varbitbool
void IS NOT DISTINCT FROM unknownbool
+ + + + +
LIKEReturn
string LIKE stringbool
+ + + + +
SIMILAR TOReturn
string SIMILAR TO stringbool
+ + + + + + + + +
^Return
decimal ^ decimaldecimal
decimal ^ intdecimal
float ^ floatfloat
int ^ decimaldecimal
int ^ intint
+ + + + + + +
|Return
inet | inetinet
int | intint
varbit | varbitvarbit
+ + + + + +
|/Return
|/decimaldecimal
|/floatfloat
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
||Return
bool || bool[]bool[]
bool || stringstring
bool[] || boolbool[]
bool[] || bool[]bool[]
box2d || box2dbox2d
box2d || stringstring
bytes || bytesbytes
bytes || bytes[]bytes[]
bytes[] || bytesbytes[]
bytes[] || bytes[]bytes[]
date || date[]date[]
date || stringstring
date[] || datedate[]
date[] || date[]date[]
decimal || decimal[]decimal[]
decimal || stringstring
decimal[] || decimaldecimal[]
decimal[] || decimal[]decimal[]
float || float[]float[]
float || stringstring
float[] || floatfloat[]
float[] || float[]float[]
geography || geographygeography
geography || stringstring
geometry || geometrygeometry
geometry || stringstring
inet || inet[]inet[]
inet || stringstring
inet[] || inetinet[]
inet[] || inet[]inet[]
int || int[]int[]
int || stringstring
int[] || intint[]
int[] || int[]int[]
interval || interval[]interval[]
interval || stringstring
interval[] || intervalinterval[]
interval[] || interval[]interval[]
jsonb || jsonbjsonb
jsonb || stringstring
oid || oidoid
oid || stringstring
pg_lsn || pg_lsnpg_lsn
pg_lsn || stringstring
refcursor || refcursorrefcursor
refcursor || stringstring
string || boolstring
string || box2dstring
string || datestring
string || decimalstring
string || floatstring
string || geographystring
string || geometrystring
string || inetstring
string || intstring
string || intervalstring
string || jsonbstring
string || oidstring
string || pg_lsnstring
string || refcursorstring
string || stringstring
string || string[]string[]
string || timestring
string || timestampstring
string || timestamptzstring
string || timetzstring
string || tuplestring
string || uuidstring
string || varbitstring
string[] || stringstring[]
string[] || string[]string[]
time || stringstring
time || time[]time[]
time[] || timetime[]
time[] || time[]time[]
timestamp || stringstring
timestamp || timestamp[]timestamp[]
timestamp[] || timestamptimestamp[]
timestamp[] || timestamp[]timestamp[]
timestamptz || stringstring
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timetz || stringstring
timetz || timetztimetz
tuple || stringstring
uuid || stringstring
uuid || uuid[]uuid[]
uuid[] || uuiduuid[]
uuid[] || uuid[]uuid[]
varbit || stringstring
varbit || varbitvarbit
+ + + + + +
||/Return
||/decimaldecimal
||/floatfloat
+ + + + + + + + + + + +
~Return
~inetinet
~intint
~varbitvarbit
box2d ~ box2dbool
box2d ~ geometrybool
geometry ~ box2dbool
geometry ~ geometrybool
string ~ stringbool
+ + + + +
~*Return
string ~* stringbool
diff --git a/src/current/_includes/cockroach-generated/release-24.1/sql/window_functions.md b/src/current/_includes/cockroach-generated/release-24.1/sql/window_functions.md new file mode 100644 index 00000000000..e1032ff82de --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.1/sql/window_functions.md @@ -0,0 +1,413 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cume_dist() → float

Calculates the relative rank of the current row: (number of rows preceding or peer with current row) / (total rows).

+		Immutable
dense_rank() → int

Calculates the rank of the current row without gaps; this function counts peer groups.

+		Immutable
first_value(val: bool) → bool

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: bytes) → bytes

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: date) → date

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: decimal) → decimal

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: float) → float

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: inet) → inet

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: int) → int

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: interval) → interval

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: string) → string

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: time) → time

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: uuid) → uuid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: box2d) → box2d

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geography) → geography

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geometry) → geometry

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: oid) → oid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timetz) → timetz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: varbit) → varbit

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
lag(val: bool) → bool

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: bytes) → bytes

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: date) → date

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: date, n: int) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: decimal) → decimal

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: float) → float

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: float, n: int) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: inet) → inet

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: int) → int

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: int, n: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: interval) → interval

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: string) → string

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: string, n: int) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: time) → time

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: time, n: int) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamp) → timestamp

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz) → timestamptz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: uuid) → uuid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: box2d) → box2d

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geography) → geography

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geometry) → geometry

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: jsonb) → jsonb

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: oid) → oid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn) → pg_lsn

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: refcursor) → refcursor

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timetz) → timetz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: varbit) → varbit

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
last_value(val: bool) → bool

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: bytes) → bytes

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: date) → date

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: decimal) → decimal

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: float) → float

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: inet) → inet

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: int) → int

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: interval) → interval

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: string) → string

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: time) → time

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: uuid) → uuid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: box2d) → box2d

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geography) → geography

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geometry) → geometry

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: oid) → oid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timetz) → timetz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: varbit) → varbit

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
lead(val: bool) → bool

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: bytes) → bytes

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: date) → date

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: date, n: int) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: decimal) → decimal

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: float) → float

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: float, n: int) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: inet) → inet

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: int) → int

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: int, n: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: interval) → interval

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: string) → string

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: string, n: int) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: time) → time

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: time, n: int) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamp) → timestamp

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz) → timestamptz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: uuid) → uuid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: box2d) → box2d

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geography) → geography

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geometry) → geometry

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: jsonb) → jsonb

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: oid) → oid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn) → pg_lsn

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: refcursor) → refcursor

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timetz) → timetz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: varbit) → varbit

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
nth_value(val: bool, n: int) → bool

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: bytes, n: int) → bytes

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: date, n: int) → date

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: decimal, n: int) → decimal

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: float, n: int) → float

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: inet, n: int) → inet

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: int, n: int) → int

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: interval, n: int) → interval

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: string, n: int) → string

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: time, n: int) → time

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: uuid, n: int) → uuid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: box2d, n: int) → box2d

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geography, n: int) → geography

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geometry, n: int) → geometry

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: oid, n: int) → oid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timetz, n: int) → timetz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: varbit, n: int) → varbit

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
ntile(n: int) → int

Calculates an integer ranging from 1 to n, dividing the partition as equally as possible.

+		Immutable
percent_rank() → float

Calculates the relative rank of the current row: (rank - 1) / (total rows - 1).

+		Immutable
rank() → int

Calculates the rank of the current row with gaps; same as row_number of its first peer.

+		Immutable
row_number() → int

Calculates the number of the current row within its partition, counting from 1.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-24.2/eventlog.md b/src/current/_includes/cockroach-generated/release-24.2/eventlog.md new file mode 100644 index 00000000000..b315b0d73c9 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.2/eventlog.md @@ -0,0 +1,3341 @@ +Certain notable events are reported using a structured format. +Commonly, these notable events are also copied to the table +`system.eventlog`, unless the cluster setting +`server.eventlog.enabled` is unset. + +Additionally, notable events are copied to specific external logging +channels in log messages, where they can be collected for further processing. + +The sections below document the possible notable event types +in this version of CockroachDB. For each event type, a table +documents the possible fields. A field may be omitted from +an event if its value is empty or zero. + +A field is also considered "Sensitive" if it may contain +application-specific information or personally identifiable information (PII). In that case, +the copy of the event sent to the external logging channel +will contain redaction markers in a format that is compatible +with the redaction facilities in [`cockroach debug zip`](cockroach-debug-zip.html) +and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html), +provided the `redactable` functionality is enabled on the logging sink. + +Events not documented on this page will have an unstructured format in log messages. + +## Cluster-level events + +Events in this category pertain to an entire cluster and are +not relative to any particular tenant. + +In a multi-tenant setup, the `system.eventlog` table for individual +tenants cannot contain a copy of cluster-level events; conversely, +the `system.eventlog` table in the system tenant cannot contain the +SQL-level events for individual tenants. + +Events in this category are logged to the `OPS` channel. + + +### `certs_reload` + +An event of type `certs_reload` is recorded when the TLS certificates are +reloaded/rotated from disk. + + +| Field | Description | Sensitive | +|--|--|--| +| `Success` | Whether the operation completed without errors. | no | +| `ErrorMessage` | If an error was encountered, the text of the error. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `node_decommissioned` + +An event of type `node_decommissioned` is recorded when a node is marked as +decommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_decommissioning` + +An event of type `node_decommissioning` is recorded when a node is marked as +decommissioning. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_join` + +An event of type `node_join` is recorded when a node joins the cluster. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_recommissioned` + +An event of type `node_recommissioned` is recorded when a decommissioning node is +recommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_restart` + +An event of type `node_restart` is recorded when an existing node rejoins the cluster +after being offline. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_connection_timeout` + +An event of type `node_shutdown_connection_timeout` is recorded when SQL connections remain open +during shutdown, after waiting for the server.shutdown.connections.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still open after waiting for the client to close them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.connections.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_transaction_timeout` + +An event of type `node_shutdown_transaction_timeout` is recorded when SQL transactions remain open +during shutdown, after waiting for the server.shutdown.transactions.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still running SQL transactions after waiting for the client to end them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.transactions.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `tenant_shared_service_start` + +An event of type `tenant_shared_service_start` is recorded when a tenant server +is started inside the same process as the KV layer. + + +| Field | Description | Sensitive | +|--|--|--| +| `OK` | Whether the startup was successful. | no | +| `ErrorText` | If the startup failed, the text of the error. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +### `tenant_shared_service_stop` + +An event of type `tenant_shared_service_stop` is recorded when a tenant server +is shut down inside the same process as the KV layer. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +## Debugging events + +Events in this category pertain to debugging operations performed by +operators or (more commonly) Cockroach Labs employees. These operations can +e.g. directly access and mutate internal state, breaking system invariants. + +Events in this category are logged to the `OPS` channel. + + +### `debug_recover_replica` + +An event of type `debug_recover_replica` is recorded when unsafe loss of quorum recovery is performed. + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `StoreID` | | no | +| `SurvivorReplicaID` | | no | +| `UpdatedReplicaID` | | no | +| `StartKey` | | yes | +| `EndKey` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +### `debug_send_kv_batch` + +An event of type `debug_send_kv_batch` is recorded when an arbitrary KV BatchRequest is submitted +to the cluster via the `debug send-kv-batch` CLI command. + + +| Field | Description | Sensitive | +|--|--|--| +| `BatchRequest` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +## Health events + +Events in this category pertain to the health of one or more servers. + +Events in this category are logged to the `HEALTH` channel. + + +### `runtime_stats` + +An event of type `runtime_stats` is recorded every 10 seconds as server health metrics. + + +| Field | Description | Sensitive | +|--|--|--| +| `MemRSSBytes` | The process resident set size. Expressed as bytes. | no | +| `GoroutineCount` | The number of goroutines. | no | +| `MemStackSysBytes` | The stack system memory used. Expressed as bytes. | no | +| `GoAllocBytes` | The memory allocated by Go. Expressed as bytes. | no | +| `GoTotalBytes` | The total memory allocated by Go but not released. Expressed as bytes. | no | +| `GoStatsStaleness` | The staleness of the Go memory statistics. Expressed in seconds. | no | +| `HeapFragmentBytes` | The amount of heap fragmentation. Expressed as bytes. | no | +| `HeapReservedBytes` | The amount of heap reserved. Expressed as bytes. | no | +| `HeapReleasedBytes` | The amount of heap released. Expressed as bytes. | no | +| `CGoAllocBytes` | The memory allocated outside of Go. Expressed as bytes. | no | +| `CGoTotalBytes` | The total memory allocated outside of Go but not released. Expressed as bytes. | no | +| `CGoCallRate` | The total number of calls outside of Go over time. Expressed as operations per second. | no | +| `CPUUserPercent` | The user CPU percentage. | no | +| `CPUSysPercent` | The system CPU percentage. | no | +| `GCPausePercent` | The GC pause percentage. | no | +| `GCRunCount` | The total number of GC runs. | no | +| `NetHostRecvBytes` | The bytes received on all network interfaces since this process started. | no | +| `NetHostSendBytes` | The bytes sent on all network interfaces since this process started. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Job events + +Events in this category pertain to long-running jobs that are orchestrated by +a node's job registry. These system processes can create and/or modify stored +objects during the course of their execution. + +A job might choose to emit multiple events during its execution when +transitioning from one "state" to another. +Egs: IMPORT/RESTORE will emit events on job creation and successful +completion. If the job fails, events will be emitted on job creation, +failure, and successful revert. + +Events in this category are logged to the `OPS` channel. + + +### `import` + +An event of type `import` is recorded when an import job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `restore` + +An event of type `restore` is recorded when a restore job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `status_change` + +An event of type `status_change` is recorded when a job changes statuses. + + +| Field | Description | Sensitive | +|--|--|--| +| `JobID` | The ID of the job that is changing statuses. | no | +| `JobType` | The type of the job that is changing statuses. | no | +| `Description` | A human parsable description of the status change | partially | +| `PreviousStatus` | The status that the job is transitioning out of | no | +| `NewStatus` | The status that the job has transitioned into | no | +| `RunNum` | The run number of the job. | no | +| `Error` | An error that may have occurred while the job was running. | yes | +| `FinalResumeErr` | An error that occurred that requires the job to be reverted. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Miscellaneous SQL events + +Events in this category report miscellaneous SQL events. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own system.eventlog table. + +Events in this category are logged to the `OPS` channel. + + +### `set_cluster_setting` + +An event of type `set_cluster_setting` is recorded when a cluster setting is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `set_tenant_cluster_setting` + +An event of type `set_tenant_cluster_setting` is recorded when a cluster setting override +is changed, either for another tenant or for all tenants. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | +| `TenantId` | The target Tenant ID. Empty if targeting all tenants. | no | +| `AllTenants` | Whether the override applies to all tenants. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +## SQL Access Audit Events + +Events in this category are generated when a table has been +marked as audited via `ALTER TABLE ... EXPERIMENTAL_AUDIT SET`. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SENSITIVE_ACCESS` channel. + + +### `admin_query` + +An event of type `admin_query` is recorded when a user with admin privileges (the user +is directly or indirectly a member of the admin role) executes a query. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `role_based_audit_event` + +An event of type `role_based_audit_event` is an audit event recorded when an executed query belongs to a user whose role +membership(s) correspond to any role that is enabled to emit an audit log via the sql.log.user_audit +cluster setting. + + +| Field | Description | Sensitive | +|--|--|--| +| `Role` | The configured audit role that emitted this log. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sensitive_table_access` + +An event of type `sensitive_table_access` is recorded when an access is performed to +a table marked as audited. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table being audited. | yes | +| `AccessMode` | How the table was accessed (r=read / rw=read/write). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +## SQL Execution Log + +Events in this category report executed queries. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `query_execute` + +An event of type `query_execute` is recorded when a query is executed, +and the cluster setting `sql.log.all_statements.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +## SQL Logical Schema Changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the SQL logical +schema. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SQL_SCHEMA` channel. + + +### `alter_database_add_region` + +An event of type `alter_database_add_region` is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `RegionName` | The region being added. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_drop_region` + +AlterDatabaseAddRegion is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `RegionName` | The region being dropped. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_placement` + +An event of type `alter_database_placement` is recorded when the database placement is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `Placement` | The new placement policy. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_primary_region` + +An event of type `alter_database_primary_region` is recorded when a primary region is added/modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `PrimaryRegionName` | The new primary region. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_set_zone_config_extension` + +An event of type `alter_database_set_zone_config_extension` is recorded when a zone config extension is changed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `alter_database_survival_goal` + +An event of type `alter_database_survival_goal` is recorded when the survival goal is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `SurvivalGoal` | The new survival goal | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_function_options` + +An event of type `alter_function_options` is recorded when a user-defined function's options are +altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the affected function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_index` + +An event of type `alter_index` is recorded when an index is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_index_visible` + +AlterIndex is recorded when an index visibility is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `NotVisible` | Set true if index is not visible. NOTE: THIS FIELD IS DEPRECATED in favor of invisibility. | no | +| `Invisibility` | The new invisibility of the affected index. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_sequence` + +An event of type `alter_sequence` is recorded when a sequence is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_table` + +An event of type `alter_table` is recorded when a table is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update, if any. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_type` + +EventAlterType is recorded when a user-defined type is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_column` + +An event of type `comment_on_column` is recorded when a column is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected column. | no | +| `ColumnName` | The affected column. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_constraint` + +An event of type `comment_on_constraint` is recorded when an constraint is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected constraint. | no | +| `ConstraintName` | The name of the affected constraint. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_database` + +CommentOnTable is recorded when a database is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_index` + +An event of type `comment_on_index` is recorded when an index is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_schema` + + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | Name of the affected schema. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_table` + +An event of type `comment_on_table` is recorded when a table is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_type` + +An event of type `comment_on_type` is recorded when a type is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_database` + +An event of type `create_database` is recorded when a database is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the new database. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_function` + +An event of type `create_function` is recorded when a user-defined function is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the created function. | no | +| `IsReplace` | If the new function is a replace of an existing function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_index` + +An event of type `create_index` is recorded when an index is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the new index. | no | +| `IndexName` | The name of the new index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_schema` + +An event of type `create_schema` is recorded when a schema is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the new schema. | no | +| `Owner` | The name of the owner for the new schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_sequence` + +An event of type `create_sequence` is recorded when a sequence is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the new sequence. | no | +| `Owner` | The name of the owner for the new sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_statistics` + +An event of type `create_statistics` is recorded when statistics are collected for a +table. + +Events of this type are only collected when the cluster setting +`sql.stats.post_events.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table for which the statistics were created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_table` + +An event of type `create_table` is recorded when a table is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the new table. | no | +| `Owner` | The name of the owner for the new table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_type` + +An event of type `create_type` is recorded when a user-defined type is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the new type. | no | +| `Owner` | The name of the owner for the new type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_view` + +An event of type `create_view` is recorded when a view is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the new view. | no | +| `Owner` | The name of the owner of the new view. | no | +| `ViewQuery` | The SQL selection clause used to define the view. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_database` + +An event of type `drop_database` is recorded when a database is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | no | +| `DroppedSchemaObjects` | The names of the schemas dropped by a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_function` + +An event of type `drop_function` is recorded when a user-defined function is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the dropped function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_index` + +An event of type `drop_index` is recorded when an index is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_schema` + +An event of type `drop_schema` is recorded when a schema is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_sequence` + +An event of type `drop_sequence` is recorded when a sequence is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_table` + +An event of type `drop_table` is recorded when a table is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_type` + +An event of type `drop_type` is recorded when a user-defined type is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_view` + +An event of type `drop_view` is recorded when a view is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the affected view. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `finish_schema_change` + +An event of type `finish_schema_change` is recorded when a previously initiated schema +change has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to complete. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `finish_schema_change_rollback` + +An event of type `finish_schema_change_rollback` is recorded when a previously +initiated schema change rollback has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to rollback. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `force_delete_table_data_entry` + + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_database` + +An event of type `rename_database` is recorded when a database is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The old name of the affected database. | no | +| `NewDatabaseName` | The new name of the affected database. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_function` + +An event of type `rename_function` is recorded when a user-defined function is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The old name of the affected function. | no | +| `NewFunctionName` | The new name of the affected function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_schema` + +An event of type `rename_schema` is recorded when a schema is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The old name of the affected schema. | no | +| `NewSchemaName` | The new name of the affected schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_table` + +An event of type `rename_table` is recorded when a table, sequence or view is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The old name of the affected table. | no | +| `NewTableName` | The new name of the affected table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_type` + +An event of type `rename_type` is recorded when a user-defined type is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The old name of the affected type. | no | +| `NewTypeName` | The new name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `reverse_schema_change` + +An event of type `reverse_schema_change` is recorded when an in-progress schema change +encounters a problem and is reversed. + + +| Field | Description | Sensitive | +|--|--|--| +| `Error` | The error encountered that caused the schema change to be reversed. The specific format of the error is variable and can change across releases without warning. | partially | +| `SQLSTATE` | The SQLSTATE code for the error. | no | +| `LatencyNanos` | The amount of time the schema change job took before being reverted. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `set_schema` + +An event of type `set_schema` is recorded when a table, view, sequence or type's schema is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorName` | The old name of the affected descriptor. | no | +| `NewDescriptorName` | The new name of the affected descriptor. | no | +| `DescriptorType` | The descriptor type being changed (table, view, sequence, type). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `truncate_table` + +An event of type `truncate_table` is recorded when a table is truncated. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_delete_descriptor` + +An event of type `unsafe_delete_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_delete_descriptor(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_delete_namespace_entry` + +An event of type `unsafe_delete_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_delete_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_upsert_descriptor` + +An event of type `unsafe_upsert_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_upsert_descriptor(). + + +| Field | Description | Sensitive | +|--|--|--| +| `PreviousDescriptor` | | yes | +| `NewDescriptor` | | yes | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_upsert_namespace_entry` + +An event of type `unsafe_upsert_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_upsert_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `PreviousID` | | no | +| `Force` | | no | +| `FailedValidation` | | no | +| `ValidationErrors` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +## SQL Privilege changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the privilege +grants for stored objects. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `PRIVILEGES` channel. + + +### `alter_database_owner` + +An event of type `alter_database_owner` is recorded when a database's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database being affected. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_default_privileges` + +An event of type `alter_default_privileges` is recorded when default privileges are changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | +| `RoleName` | Either role_name should be populated or for_all_roles should be true. The role having its default privileges altered. | yes | +| `ForAllRoles` | Identifies if FOR ALL ROLES is used. | no | +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `alter_function_owner` + +AlterTableOwner is recorded when the owner of a user-defined function is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The name of the affected user-defined function. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_schema_owner` + +An event of type `alter_schema_owner` is recorded when a schema's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_table_owner` + +An event of type `alter_table_owner` is recorded when the owner of a table, view or sequence is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected object. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_type_owner` + +An event of type `alter_type_owner` is recorded when the owner of a user-defiend type is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `change_database_privilege` + +An event of type `change_database_privilege` is recorded when privileges are +added to / removed from a user for a database object. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_function_privilege` + + + +| Field | Description | Sensitive | +|--|--|--| +| `FuncName` | The name of the affected function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_schema_privilege` + +An event of type `change_schema_privilege` is recorded when privileges are added to / +removed from a user for a schema object. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_table_privilege` + +An event of type `change_table_privilege` is recorded when privileges are added to / removed +from a user for a table, sequence or view object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_type_privilege` + +An event of type `change_type_privilege` is recorded when privileges are added to / +removed from a user for a type object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +## SQL Session events + +Events in this category report SQL client connections +and sessions. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SESSIONS` channel. + + +### `client_authentication_failed` + +An event of type `client_authentication_failed` is reported when a client session +did not authenticate successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Reason` | The reason for the authentication failure. See below for possible values for type `AuthFailReason`. | no | +| `Detail` | The detailed error for the authentication failure. | partially | +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_info` + +An event of type `client_authentication_info` is reported for intermediate +steps during the authentication process. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used, once known. | no | +| `Info` | The authentication progress message. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_ok` + +An event of type `client_authentication_ok` is reported when a client session +was authenticated successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_connection_end` + +An event of type `client_connection_end` is reported when a client connection +is closed. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_connection_start` + +An event of type `client_connection_start` is reported when a client connection +is established. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_session_end` + +An event of type `client_session_end` is reported when a client session +is completed. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +## SQL Slow Query Log + +Events in this category report slow query execution. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_PERF` channel. + + +### `large_row` + +An event of type `large_row` is recorded when a statement tries to write a row larger than +cluster setting `sql.guardrails.max_row_size_log` to the database. Multiple +LargeRow events will be recorded for statements writing multiple large rows. +LargeRow events are recorded before the transaction commits, so in the case +of transaction abort there will not be a corresponding row in the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query` + +An event of type `slow_query` is recorded when a query triggers the "slow query" condition. + +As of this writing, the condition requires: +- the cluster setting `sql.log.slow_query.latency_threshold` +set to a non-zero value, AND +- EITHER of the following conditions: +- the actual age of the query exceeds the configured threshold; AND/OR +- the query performs a full table/index scan AND the cluster setting +`sql.log.slow_query.experimental_full_table_scans.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit` + +An event of type `txn_rows_read_limit` is recorded when a transaction tries to read more rows than +cluster setting `sql.defaults.transaction_rows_read_log`. There will only be +a single record for a single transaction (unless it is retried) even if there +are more statement within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit` + +An event of type `txn_rows_written_limit` is recorded when a transaction tries to write more rows +than cluster setting `sql.defaults.transaction_rows_written_log`. There will +only be a single record for a single transaction (unless it is retried) even +if there are more mutation statements within the transaction that haven't +been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL Slow Query Log (Internal) + +Events in this category report slow query execution by +internal executors, i.e., when CockroachDB internally issues +SQL statements. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_INTERNAL_PERF` channel. + + +### `large_row_internal` + +An event of type `large_row_internal` is recorded when an internal query tries to write a row +larger than cluster settings `sql.guardrails.max_row_size_log` or +`sql.guardrails.max_row_size_err` to the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query_internal` + +An event of type `slow_query_internal` is recorded when a query triggers the "slow query" condition, +and the cluster setting `sql.log.slow_query.internal_queries.enabled` is +set. +See the documentation for the event type `slow_query` for details about +the "slow query" condition. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit_internal` + +An event of type `txn_rows_read_limit_internal` is recorded when an internal transaction tries to +read more rows than cluster setting `sql.defaults.transaction_rows_read_log` +or `sql.defaults.transaction_rows_read_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit_internal` + +An event of type `txn_rows_written_limit_internal` is recorded when an internal transaction tries to +write more rows than cluster setting +`sql.defaults.transaction_rows_written_log` or +`sql.defaults.transaction_rows_written_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL User and Role operations + +Events in this category pertain to SQL statements that modify the +properties of users and roles. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `USER_ADMIN` channel. + + +### `alter_role` + +An event of type `alter_role` is recorded when a role is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | +| `Options` | The options set on the user/role. | no | +| `SetInfo` | Information corresponding to an ALTER ROLE SET statement. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_role` + +An event of type `create_role` is recorded when a role is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the new user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_role` + +An event of type `drop_role` is recorded when a role is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `grant_role` + +An event of type `grant_role` is recorded when a role is granted. + + +| Field | Description | Sensitive | +|--|--|--| +| `GranteeRoles` | The roles being granted to. | yes | +| `Members` | The roles being granted. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `password_hash_converted` + +An event of type `password_hash_converted` is recorded when the password credentials +are automatically converted server-side. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the user/role whose credentials have been converted. | yes | +| `OldMethod` | The previous hash method. | no | +| `NewMethod` | The new hash method. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Storage telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `level_stats` + +An event of type `level_stats` contains per-level statistics for an LSM. + + +| Field | Description | Sensitive | +|--|--|--| +| `Level` | level is the level ID in a LSM (e.g. level(L0) == 0, etc.) | no | +| `NumFiles` | num_files is the number of files in the level (gauge). | no | +| `SizeBytes` | size_bytes is the size of the level, in bytes (gauge). | no | +| `Score` | score is the compaction score of the level (gauge). | no | +| `BytesIn` | bytes_in is the number of bytes written to this level (counter). | no | +| `BytesIngested` | bytes_ingested is the number of bytes ingested into this level (counter). | no | +| `BytesMoved` | bytes_moved is the number of bytes moved into this level via a move-compaction (counter). | no | +| `BytesRead` | bytes_read is the number of bytes read from this level, during compactions (counter). | no | +| `BytesCompacted` | bytes_compacted is the number of bytes written to this level during compactions (counter). | no | +| `BytesFlushed` | bytes flushed is the number of bytes flushed to this level. This value is always zero for levels other than L0 (counter). | no | +| `TablesCompacted` | tables_compacted is the count of tables compacted into this level (counter). | no | +| `TablesFlushed` | tables_flushed is the count of tables flushed into this level (counter). | no | +| `TablesIngested` | tables_ingested is the count of tables ingested into this level (counter). | no | +| `TablesMoved` | tables_moved is the count of tables moved into this level via move-compactions (counter). | no | +| `NumSublevels` | num_sublevel is the count of sublevels for the level. This value is always zero for levels other than L0 (gauge). | no | + + + +### `store_stats` + +An event of type `store_stats` contains per store stats. + +Note that because stats are scoped to the lifetime of the process, counters +(and certain gauges) will be reset across node restarts. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeId` | node_id is the ID of the node. | no | +| `StoreId` | store_id is the ID of the store. | no | +| `Levels` | levels is a nested message containing per-level statistics. | yes | +| `CacheSize` | cache_size is the size of the cache for the store, in bytes (gauge). | no | +| `CacheCount` | cache_count is the number of items in the cache (gauge). | no | +| `CacheHits` | cache_hits is the number of cache hits (counter). | no | +| `CacheMisses` | cache_misses is the number of cache misses (counter). | no | +| `CompactionCountDefault` | compaction_count_default is the count of default compactions (counter). | no | +| `CompactionCountDeleteOnly` | compaction_count_delete_only is the count of delete-only compactions (counter). | no | +| `CompactionCountElisionOnly` | compaction_count_elision_only is the count of elision-only compactions (counter). | no | +| `CompactionCountMove` | compaction_count_move is the count of move-compactions (counter). | no | +| `CompactionCountRead` | compaction_count_read is the count of read-compactions (counter). | no | +| `CompactionCountRewrite` | compaction_count_rewrite is the count of rewrite-compactions (counter). | no | +| `CompactionNumInProgress` | compactions_num_in_progress is the number of compactions in progress (gauge). | no | +| `CompactionMarkedFiles` | compaction_marked_files is the count of files marked for compaction (gauge). | no | +| `FlushCount` | flush_count is the number of flushes (counter). | no | +| `FlushIngestCount` | | no | +| `FlushIngestTableCount` | | no | +| `FlushIngestTableBytes` | | no | +| `IngestCount` | ingest_count is the number of successful ingest operations (counter). | no | +| `MemtableSize` | memtable_size is the total size allocated to all memtables and (large) batches, in bytes (gauge). | no | +| `MemtableCount` | memtable_count is the count of memtables (gauge). | no | +| `MemtableZombieCount` | memtable_zombie_count is the count of memtables no longer referenced by the current DB state, but still in use by an iterator (gauge). | no | +| `MemtableZombieSize` | memtable_zombie_size is the size, in bytes, of all zombie memtables (gauge). | no | +| `WalLiveCount` | wal_live_count is the count of live WAL files (gauge). | no | +| `WalLiveSize` | wal_live_size is the size, in bytes, of live data in WAL files. With WAL recycling, this value is less than the actual on-disk size of the WAL files (gauge). | no | +| `WalObsoleteCount` | wal_obsolete_count is the count of obsolete WAL files (gauge). | no | +| `WalObsoleteSize` | wal_obsolete_size is the size of obsolete WAL files, in bytes (gauge). | no | +| `WalPhysicalSize` | wal_physical_size is the size, in bytes, of the WAL files on disk (gauge). | no | +| `WalBytesIn` | wal_bytes_in is the number of logical bytes written to the WAL (counter). | no | +| `WalBytesWritten` | wal_bytes_written is the number of bytes written to the WAL (counter). | no | +| `TableObsoleteCount` | table_obsolete_count is the number of tables which are no longer referenced by the current DB state or any open iterators (gauge). | no | +| `TableObsoleteSize` | table_obsolete_size is the size, in bytes, of obsolete tables (gauge). | no | +| `TableZombieCount` | table_zombie_count is the number of tables no longer referenced by the current DB state, but are still in use by an open iterator (gauge). | no | +| `TableZombieSize` | table_zombie_size is the size, in bytes, of zombie tables (gauge). | no | +| `RangeKeySetsCount` | range_key_sets_count is the approximate count of internal range key sets in the store. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `captured_index_usage_stats` + +An event of type `captured_index_usage_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `TotalReadCount` | TotalReadCount is the number of times the index has been read. | no | +| `LastRead` | LastRead is the timestamp at which the index was last read. | no | +| `TableID` | TableID is the ID of the table on which the index was created. This is same as descpb.TableID and is unique within the cluster. | no | +| `IndexID` | IndexID is the ID of the index within the scope of the given table. | no | +| `DatabaseName` | DatabaseName is the name of the database in which the index was created. | no | +| `TableName` | TableName is the name of the table on which the index was created. | no | +| `IndexName` | IndexName is the name of the index within the scope of the given table. | no | +| `IndexType` | IndexType is the type of the index. Index types include "primary" and "secondary". | no | +| `IsUnique` | IsUnique indicates if the index has a UNIQUE constraint. | no | +| `IsInverted` | IsInverted indicates if the index is an inverted index. | no | +| `CreatedAt` | CreatedAt is the timestamp at which the index was created. | no | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `changefeed_emitted_bytes` + +An event of type `changefeed_emitted_bytes` is an event representing the bytes emitted by a changefeed over an interval. + + +| Field | Description | Sensitive | +|--|--|--| +| `JobId` | The job id for enterprise changefeeds. | no | +| `EmittedBytes` | The number of bytes emitted. | no | +| `EmittedMessages` | The number of messages emitted. | no | +| `LoggingInterval` | The time period in nanoseconds between emitting telemetry events of this type (per-aggregator). | no | +| `Closing` | Flag to indicate that the changefeed is closing. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | + +### `changefeed_failed` + +An event of type `changefeed_failed` is an event for any Changefeed failure since the plan hook +was triggered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FailureType` | The reason / environment with which the changefeed failed (ex: connection_closed, changefeed_behind) | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | + +### `create_changefeed` + +An event of type `create_changefeed` is an event for any CREATE CHANGEFEED query that +successfully starts running. Failed CREATE statements will show up as +ChangefeedFailed events. + + +| Field | Description | Sensitive | +|--|--|--| +| `Transformation` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | + +### `hot_ranges_stats` + +An event of type `hot_ranges_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `Qps` | | no | +| `DatabaseName` | DatabaseName is the name of the database in which the index was created. | yes | +| `TableName` | TableName is the name of the table on which the index was created. | yes | +| `IndexName` | IndexName is the name of the index within the scope of the given table. | yes | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | yes | +| `LeaseholderNodeID` | LeaseholderNodeID indicates the Node ID that is the current leaseholder for the given range. | no | +| `WritesPerSecond` | Writes per second is the recent number of keys written per second on this range. | no | +| `ReadsPerSecond` | Reads per second is the recent number of keys read per second on this range. | no | +| `WriteBytesPerSecond` | Write bytes per second is the recent number of bytes written per second on this range. | no | +| `ReadBytesPerSecond` | Read bytes per second is the recent number of bytes read per second on this range. | no | +| `CPUTimePerSecond` | CPU time per second is the recent cpu usage in nanoseconds of this range. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `m_v_c_c_iterator_stats` + +Internal storage iteration statistics for a single execution. + + +| Field | Description | Sensitive | +|--|--|--| +| `StepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `StepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `BlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `BlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `KeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `ValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | + + + +### `recovery_event` + +An event of type `recovery_event` is an event that is logged on every invocation of BACKUP, +RESTORE, and on every BACKUP schedule creation, with the appropriate subset +of fields populated depending on the type of event. This event is is also +logged whenever a BACKUP and RESTORE job completes or fails. + + +| Field | Description | Sensitive | +|--|--|--| +| `RecoveryType` | RecoveryType is the type of recovery described by this event, which is one of - backup - scheduled_backup - create_schedule - restore

It can also be a job event corresponding to the recovery, which is one of - backup_job - scheduled_backup_job - restore_job | no | +| `TargetScope` | TargetScope is the largest scope of the targets that the user is backing up or restoring based on the following order: table < schema < database < full cluster. | no | +| `IsMultiregionTarget` | IsMultiregionTarget is true if any of the targets contain objects with multi-region primitives. | no | +| `TargetCount` | TargetCount is the number of targets the in the BACKUP/RESTORE. | no | +| `DestinationSubdirType` | DestinationSubdirType is - latest: if using the latest subdir - standard: if using a date-based subdir - custom: if using a custom subdir that's not date-based | no | +| `DestinationStorageTypes` | DestinationStorageTypes are the types of storage that the user is backing up to or restoring from. | no | +| `DestinationAuthTypes` | DestinationAuthTypes are the types of authentication methods that the user is using to access the destination storage. | no | +| `IsLocalityAware` | IsLocalityAware indicates if the BACKUP or RESTORE is locality aware. | no | +| `AsOfInterval` | AsOfInterval is the time interval in nanoseconds between the statement timestamp and the timestamp resolved by the AS OF SYSTEM TIME expression. The interval is expressed in nanoseconds. | no | +| `WithRevisionHistory` | WithRevisionHistory is true if the BACKUP includes revision history. | no | +| `HasEncryptionPassphrase` | HasEncryptionPassphrase is true if the user provided an encryption passphrase to encrypt/decrypt their backup. | no | +| `KMSType` | KMSType is the type of KMS the user is using to encrypt/decrypt their backup. | no | +| `KMSCount` | KMSCount is the number of KMS the user is using. | no | +| `Options` | Options contain all the names of the options specified by the user in the BACKUP or RESTORE statement. For options that are accompanied by a value, only those with non-empty values will be present.

It's important to note that there are no option values anywhere in the event payload. Future changes to telemetry should refrain from adding values to the payload unless they are properly redacted. | no | +| `DebugPauseOn` | DebugPauseOn is the type of event that the restore should pause on for debugging purposes. Currently only "error" is supported. | no | +| `JobID` | JobID is the ID of the BACKUP/RESTORE job. | no | +| `ResultStatus` | ResultStatus indicates whether the job succeeded or failed. | no | +| `ErrorText` | ErrorText is the text of the error that caused the job to fail. | partially | +| `RecurringCron` | RecurringCron is the crontab for the incremental backup. | no | +| `FullBackupCron` | FullBackupCron is the crontab for the full backup. | no | +| `CustomFirstRunTime` | CustomFirstRunTime is the timestamp for the user configured first run time. Expressed as nanoseconds since the Unix epoch. | no | +| `OnExecutionFailure` | OnExecutionFailure describes the desired behavior if the schedule fails to execute. | no | +| `OnPreviousRunning` | OnPreviousRunning describes the desired behavior if the previously scheduled BACKUP is still running. | no | +| `IgnoreExistingBackup` | IgnoreExistingBackup is true iff the BACKUP schedule should still be created even if a backup is already present in its destination. | no | +| `ApplicationName` | The application name for the session where recovery event was created. | no | +| `NumRows` | NumRows is the number of rows successfully imported, backed up or restored. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `sampled_exec_stats` + +An event of type `sampled_exec_stats` contains execution statistics that apply to both statements +and transactions. These stats as a whole are collected using a sampling approach. +These exec stats are meant to contain the same fields as ExecStats in +apps_stats.proto but are for a single execution rather than aggregated executions. +Fields in this struct should be updated in sync with apps_stats.proto. + + +| Field | Description | Sensitive | +|--|--|--| +| `NetworkBytes` | NetworkBytes collects the number of bytes sent over the network. | no | +| `MaxMemUsage` | MaxMemUsage collects the maximum memory usage that occurred on a node. | no | +| `ContentionTime` | ContentionTime collects the time in seconds statements in the transaction spent contending. | no | +| `NetworkMessages` | NetworkMessages collects the number of messages that were sent over the network. | no | +| `MaxDiskUsage` | MaxDiskUsage collects the maximum temporary disk usage that occurred. This is set in cases where a query had to spill to disk, e.g. when performing a large sort where not all of the tuples fit in memory. | no | +| `CPUSQLNanos` | CPUSQLNanos collects the CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `MVCCIteratorStats` | Internal storage iteration statistics. | yes | + + + +### `sampled_query` + +An event of type `sampled_query` is the SQL query event logged to the telemetry channel. It +contains common SQL event/execution details. + + +| Field | Description | Sensitive | +|--|--|--| +| `SkippedQueries` | skipped_queries indicate how many SQL statements were not considered for sampling prior to this one. If the field is omitted, or its value is zero, this indicates that no statement was omitted since the last event. | no | +| `CostEstimate` | Cost of the query as estimated by the optimizer. | no | +| `Distribution` | The distribution of the DistSQL query plan (local, full, or partial). | no | +| `PlanGist` | The query's plan gist bytes as a base64 encoded string. | no | +| `SessionID` | SessionID is the ID of the session that initiated the query. | no | +| `Database` | Name of the database that initiated the query. | no | +| `StatementID` | Statement ID of the query. | no | +| `TransactionID` | Transaction ID of the query. | no | +| `MaxFullScanRowsEstimate` | Maximum number of rows scanned by a full scan, as estimated by the optimizer. | no | +| `TotalScanRowsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer. | no | +| `OutputRowsEstimate` | The number of rows output by the query, as estimated by the optimizer. | no | +| `StatsAvailable` | Whether table statistics were available to the optimizer when planning the query. | no | +| `NanosSinceStatsCollected` | The maximum number of nanoseconds that have passed since stats were collected on any table scanned by this query. | no | +| `BytesRead` | The number of bytes read from disk. | no | +| `RowsRead` | The number of rows read from disk. | no | +| `RowsWritten` | The number of rows written. | no | +| `InnerJoinCount` | The number of inner joins in the query plan. | no | +| `LeftOuterJoinCount` | The number of left (or right) outer joins in the query plan. | no | +| `FullOuterJoinCount` | The number of full outer joins in the query plan. | no | +| `SemiJoinCount` | The number of semi joins in the query plan. | no | +| `AntiJoinCount` | The number of anti joins in the query plan. | no | +| `IntersectAllJoinCount` | The number of intersect all joins in the query plan. | no | +| `ExceptAllJoinCount` | The number of except all joins in the query plan. | no | +| `HashJoinCount` | The number of hash joins in the query plan. | no | +| `CrossJoinCount` | The number of cross joins in the query plan. | no | +| `IndexJoinCount` | The number of index joins in the query plan. | no | +| `LookupJoinCount` | The number of lookup joins in the query plan. | no | +| `MergeJoinCount` | The number of merge joins in the query plan. | no | +| `InvertedJoinCount` | The number of inverted joins in the query plan. | no | +| `ApplyJoinCount` | The number of apply joins in the query plan. | no | +| `ZigZagJoinCount` | The number of zig zag joins in the query plan. | no | +| `ContentionNanos` | The duration of time in nanoseconds that the query experienced contention. | no | +| `Regions` | The regions of the nodes where SQL processors ran. | no | +| `NetworkBytesSent` | The number of network bytes sent by nodes for this query. | no | +| `MaxMemUsage` | The maximum amount of memory usage by nodes for this query. | no | +| `MaxDiskUsage` | The maximum amount of disk usage by nodes for this query. | no | +| `KVBytesRead` | The number of bytes read at the KV layer for this query. | no | +| `KVPairsRead` | The number of key-value pairs read at the KV layer for this query. | no | +| `KVRowsRead` | The number of rows read at the KV layer for this query. | no | +| `NetworkMessages` | The number of network messages sent by nodes for this query. | no | +| `IndexRecommendations` | Generated index recommendations for this query. | no | +| `ScanCount` | The number of scans in the query plan. | no | +| `ScanWithStatsCount` | The number of scans using statistics (including forecasted statistics) in the query plan. | no | +| `ScanWithStatsForecastCount` | The number of scans using forecasted statistics in the query plan. | no | +| `TotalScanRowsWithoutForecastsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer without using forecasts. | no | +| `NanosSinceStatsForecasted` | The greatest quantity of nanoseconds that have passed since the forecast time (or until the forecast time, if it is in the future, in which case it will be negative) for any table with forecasted stats scanned by this query. | no | +| `Indexes` | The list of indexes used by this query. | no | +| `CpuTimeNanos` | Collects the cumulative CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `KvGrpcCalls` | The number of grpc calls done to get data form KV nodes | no | +| `KvTimeNanos` | Cumulated time spent waiting for a KV request. This includes disk IO time and potentially network time (if any of the keys are not local). | no | +| `ServiceLatencyNanos` | The time to service the query, from start of parse to end of execute. | no | +| `OverheadLatencyNanos` | The difference between service latency and the sum of parse latency + plan latency + run latency . | no | +| `RunLatencyNanos` | The time to run the query and fetch or compute the result rows. | no | +| `PlanLatencyNanos` | The time to transform the AST into a logical query plan. | no | +| `IdleLatencyNanos` | The time between statement executions in a transaction | no | +| `ParseLatencyNanos` | The time to transform the SQL string into an abstract syntax tree (AST). | no | +| `MvccStepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccStepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccBlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `MvccBlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `MvccKeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `SchemaChangerMode` | SchemaChangerMode is the mode that was used to execute the schema change, if any. | no | +| `SQLInstanceIDs` | SQLInstanceIDs is a list of all the SQL instances used in this statement's execution. | no | +| `KVNodeIDs` | KVNodeIDs is a list of all the KV nodes used in this statement's execution. | no | +| `StatementFingerprintID` | Statement fingerprint ID of the query. | no | +| `UsedFollowerRead` | UsedFollowerRead indicates whether at least some reads were served by the follower replicas. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sampled_transaction` + +An event of type `sampled_transaction` is the event logged to telemetry at the end of transaction execution. + + +| Field | Description | Sensitive | +|--|--|--| +| `User` | User is the user account that triggered the transaction. The special usernames `root` and `node` are not considered sensitive. | depends | +| `ApplicationName` | ApplicationName is the application name for the session where the transaction was executed. This is included in the event to ease filtering of logging output by application. | no | +| `TxnCounter` | TxnCounter is the sequence number of the SQL transaction inside its session. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `TransactionID` | TransactionID is the id of the transaction. | no | +| `Committed` | Committed indicates if the transaction committed successfully. We want to include this value even if it is false. | no | +| `ImplicitTxn` | ImplicitTxn indicates if the transaction was an implicit one. We want to include this value even if it is false. | no | +| `StartTimeUnixNanos` | StartTimeUnixNanos is the time the transaction was started. Expressed as unix time in nanoseconds. | no | +| `EndTimeUnixNanos` | EndTimeUnixNanos the time the transaction finished (either committed or aborted). Expressed as unix time in nanoseconds. | no | +| `ServiceLatNanos` | ServiceLatNanos is the time to service the whole transaction, from start to end of execution. | no | +| `SQLSTATE` | SQLSTATE is the SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | ErrorText is the text of the error if any. | partially | +| `NumRetries` | NumRetries is the number of time when the txn was retried automatically by the server. | no | +| `LastAutoRetryReason` | LastAutoRetryReason is a string containing the reason for the last automatic retry. | partially | +| `NumRows` | NumRows is the total number of rows returned across all statements. | no | +| `RetryLatNanos` | RetryLatNanos is the amount of time spent retrying the transaction. | no | +| `CommitLatNanos` | CommitLatNanos is the amount of time spent committing the transaction after all statement operations. | no | +| `IdleLatNanos` | IdleLatNanos is the amount of time spent waiting for the client to send statements while the transaction is open. | no | +| `BytesRead` | BytesRead is the number of bytes read from disk. | no | +| `RowsRead` | RowsRead is the number of rows read from disk. | no | +| `RowsWritten` | RowsWritten is the number of rows written to disk. | no | +| `SampledExecStats` | SampledExecStats is a nested field containing execution statistics. This field will be omitted if the stats were not sampled. | yes | +| `SkippedTransactions` | SkippedTransactions is the number of transactions that were skipped as part of sampling prior to this one. We only count skipped transactions when telemetry logging is enabled and the sampling mode is set to "transaction". | no | +| `TransactionFingerprintID` | TransactionFingerprintID is the fingerprint ID of the transaction. This can be used to find the transaction in the console. | no | +| `StatementFingerprintIDs` | StatementFingerprintIDs is an array of statement fingerprint IDs belonging to this transaction. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_descriptor` + +An event of type `schema_descriptor` is an event for schema telemetry, whose purpose is +to take periodic snapshots of the cluster's SQL schema and publish them in +the telemetry log channel. For all intents and purposes, the data in such a +snapshot can be thought of the outer join of certain system tables: +namespace, descriptor, and at some point perhaps zones, etc. + +Snapshots are too large to conveniently be published as a single log event, +so instead they're broken down into SchemaDescriptor events which +contain the data in one record of this outer join projection. These events +are prefixed by a header (a SchemaSnapshotMetadata event). + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of the snapshot that this event is part of. | no | +| `ParentDatabaseID` | ParentDatabaseID matches the same key column in system.namespace. | no | +| `ParentSchemaID` | ParentSchemaID matches the same key column in system.namespace. | no | +| `Name` | Name matches the same key column in system.namespace. | no | +| `DescID` | DescID matches the 'id' column in system.namespace and system.descriptor. | no | +| `Desc` | Desc matches the 'descriptor' column in system.descriptor. Some contents of the descriptor may be redacted to prevent leaking PII. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_snapshot_metadata` + +An event of type `schema_snapshot_metadata` is an event describing a schema snapshot, which +is a set of SchemaDescriptor messages sharing the same SnapshotID. + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of this snapshot. | no | +| `NumRecords` | NumRecords is how many SchemaDescriptor events are in the snapshot. | no | +| `AsOfTimestamp` | AsOfTimestamp is when the snapshot was taken. This is equivalent to the timestamp given in the AS OF SYSTEM TIME clause when querying the namespace and descriptor tables in the system database. Expressed as nanoseconds since the Unix epoch. | no | +| `Errors` | Errors records any errors encountered when post-processing this snapshot, which includes the redaction of any potential PII. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Zone config events + +Events in this category pertain to zone configuration changes on +the SQL schema or system ranges. + +When zone configs apply to individual tables or other objects in a +SQL logical schema, they are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these zone config events are preserved +in each tenant's own `system.eventlog` table. + +When they apply to cluster-level ranges (e.g., the system zone config), +they are stored in the system tenant's own `system.eventlog` table. + +Events in this category are logged to the `OPS` channel. + + +### `remove_zone_config` + +An event of type `remove_zone_config` is recorded when a zone config is removed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `set_zone_config` + +An event of type `set_zone_config` is recorded when a zone config is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `ResolvedOldConfig` | The string representation of the resolved old zone config. This is not necessarily the same as the zone config that was previously set -- as it includes the resolved values of the zone config options. In other words, a zone config that hasn't been properly "set" yet (and inherits from its parent) will have a resolved_old_config that has details of the values it inherits from its parent. This is particularly useful to get a proper diff between the old and new zone config. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + + + + +## Enumeration types + +### `AuthFailReason` + +AuthFailReason is the inventory of possible reasons for an +authentication failure. + + +| Value | Textual alias in code or documentation | Description | +|--|--|--| +| 0 | UNKNOWN | is reported when the reason is unknown. | +| 1 | USER_RETRIEVAL_ERROR | occurs when there was an internal error accessing the principals. | +| 2 | USER_NOT_FOUND | occurs when the principal is unknown. | +| 3 | LOGIN_DISABLED | occurs when the user does not have LOGIN privileges. | +| 4 | METHOD_NOT_FOUND | occurs when no HBA rule matches or the method does not exist. | +| 5 | PRE_HOOK_ERROR | occurs when the authentication handshake encountered a protocol error. | +| 6 | CREDENTIALS_INVALID | occurs when the client-provided credentials were invalid. | +| 7 | CREDENTIALS_EXPIRED | occur when the credentials provided by the client are expired. | +| 8 | NO_REPLICATION_ROLEOPTION | occurs when the connection requires a replication role option, but the user does not have it. | + + + diff --git a/src/current/_includes/cockroach-generated/release-24.2/logformats.md b/src/current/_includes/cockroach-generated/release-24.2/logformats.md new file mode 100644 index 00000000000..89580c9fc15 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.2/logformats.md @@ -0,0 +1,382 @@ + +The supported log output formats are documented below. + + +- [`crdb-v1`](#format-crdb-v1) + +- [`crdb-v1-count`](#format-crdb-v1-count) + +- [`crdb-v1-tty`](#format-crdb-v1-tty) + +- [`crdb-v1-tty-count`](#format-crdb-v1-tty-count) + +- [`crdb-v2`](#format-crdb-v2) + +- [`crdb-v2-tty`](#format-crdb-v2-tty) + +- [`json`](#format-json) + +- [`json-compact`](#format-json-compact) + +- [`json-fluent`](#format-json-fluent) + +- [`json-fluent-compact`](#format-json-fluent-compact) + + + +## Format `crdb-v1` + + +This is a legacy file format used from CockroachDB v1.0. + +Each log entry is emitted using a common prefix, described below, followed by: + +- The logging context tags enclosed between `[` and `]`, if any. It is possible + for this to be omitted if there were no context tags. +- Optionally, a counter column, if the option 'show-counter' is enabled. See below for details. +- the text of the log entry. + +Beware that the text of the log entry can span multiple lines. +The following caveats apply: + +- The text of the log entry can start with text enclosed between `[` and `]`. + If there were no logging tags to start with, it is not possible to distinguish between + logging context tag information and a `[...]` string in the main text of the + log entry. This means that this format is ambiguous. + + To remove this ambiguity, you can use the option 'show-counter'. + +- The text of the log entry can embed arbitrary application-level strings, + including strings that represent log entries. In particular, an accident + of implementation can cause the common entry prefix (described below) + to also appear on a line of its own, as part of the payload of a previous + log entry. There is no automated way to recognize when this occurs. + Care must be taken by a human observer to recognize these situations. + +- The log entry parser provided by CockroachDB to read log files is faulty + and is unable to recognize the aforementioned pitfall; nor can it read + entries larger than 64KiB successfully. Generally, use of this internal + log entry parser is discouraged for entries written with this format. + +See the newer format `crdb-v2` for an alternative +without these limitations. + +### Header lines + +At the beginning of each file, a header is printed using a similar format as +regular log entries. This header reports when the file was created, +which parameters were used to start the server, the server identifiers +if known, and other metadata about the running process. + +- This header appears to be logged at severity `INFO` (with an `I` prefix + at the start of the line) even though it does not really have a severity. +- The header is printed unconditionally even when a filter is configured to + omit entries at the `INFO` level. + +### Common log entry prefix + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker tags counter + +Reminder, the tags may be omitted; and the counter is only printed if the option +'show-counter' is specified. + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (omitted if zero for use by tests). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. | +| line | The line number where the entry originated. | +| marker | Redactability marker ` + redactableIndicator + ` (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. May be absent. | +| counter | The entry counter. Only included if 'show-counter' is enabled. | + +The redactability marker can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. + +If the marker ` + redactableIndicator + ` is present, the remainder of the log entry +contains delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `show-counter` | Whether to include the counter column in the line header. Without it, the format may be ambiguous due to the optionality of tags. | +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v1-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: none` + + +## Format `crdb-v1-tty` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: false` +- `colors: auto` + + +## Format `crdb-v1-tty-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: auto` + + +## Format `crdb-v2` + +This is the main file format used from CockroachDB v21.1. + +Each log entry is emitted using a common prefix, described below, +followed by the text of the log entry. + +### Entry format + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker [tags...] counter cont + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (zero when cannot be determined). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. Also see below. | +| line | The line number where the entry originated. | +| marker | Redactability marker "⋮" (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. See below. | +| counter | The optional entry counter (see below for details). | +| cont | Continuation mark for structured and multi-line entries. See below. | + +The `chan@` prefix before the file name indicates the logging channel, +and is omitted if the channel is `DEV`. + +The file name may be prefixed by the string `(gostd) ` to indicate +that the log entry was produced inside the Go standard library, instead +of a CockroachDB component. Entry parsers must be configured to ignore this prefix +when present. + +`marker` can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. +If the marker "⋮" is present, the remainder of the log entry +contains delimiters (‹...›) +around fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +when log redaction is requested. + +The logging `tags` are enclosed between square brackets `[...]`, +and the syntax `[-]` is used when there are no logging tags +associated with the log entry. + +`counter` is numeric, and is incremented for every +log entry emitted to this sink. (There is thus one counter sequence per +sink.) For entries that do not have a counter value +associated (e.g., header entries in file sinks), the counter position +in the common prefix is empty: `tags` is then +followed by two ASCII space characters, instead of one space; the `counter`, +and another space. The presence of the two ASCII spaces indicates +reliably that no counter was present. + +`cont` is a format/continuation indicator: + +| Continuation indicator | ASCII | Description | +|------------------------|-------|--| +| space | 0x32 | Start of an unstructured entry. | +| equal sign, "=" | 0x3d | Start of a structured entry. | +| exclamation mark, "!" | 0x21 | Start of an embedded stack trace. | +| plus sign, "+" | 0x2b | Continuation of a multi-line entry. The payload contains a newline character at this position. | +| vertical bar | 0x7c | Continuation of a large entry. | + +### Examples + +Example single-line unstructured entry: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 started with engine type ‹2› +~~~ + +Example multi-line unstructured entry: + +~~~ +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 node startup completed: +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 +CockroachDB node starting at 2021-01-16 21:49 (took 0.0s) +~~~ + +Example structured entry: + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventType":"node_restart"} +~~~ + +Example long entries broken up into multiple lines: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.... +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 |aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +~~~ + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventTy... +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 |pe":"node_restart"} +~~~ + +### Backward-compatibility notes + +Entries in this format can be read by most `crdb-v1` log parsers, +in particular the one included in the DB console and +also the [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +facility. + +However, implementers of previous version parsers must +understand that the logging tags field is now always +included, and the lack of logging tags is included +by a tag string set to `[-]`. + +Likewise, the entry counter is now also always included, +and there is a special character after `counter` +to indicate whether the remainder of the line is a +structured entry, or a continuation of a previous entry. + +Finally, in the previous format, structured entries +were prefixed with the string `Structured entry: `. In +the new format, they are prefixed by the `=` continuation +indicator. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v2-tty` + +This format name is an alias for 'crdb-v2' with +the following format option defaults: + +- `colors: auto` + + +## Format `json` + +This format emits log entries as a JSON payload. + +The JSON object is guaranteed to not contain unescaped newlines +or other special characters, and the entry as a whole is followed +by a newline character. This makes the format suitable for +processing over a stream unambiguously. + +Each entry contains at least the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `tag` | `tag` | (Only if the option `fluent-tag: true` is given.) A Fluent tag for the event, formed by the process name and the logging channel. | +| `d` | `datetime` | The pretty-printed date/time of the event timestamp, if enabled via options. | +| `f` | `file` | The name of the source file where the event was emitted. | +| `g` | `goroutine` | The identifier of the goroutine where the event was emitted. | +| `l` | `line` | The line number where the event was emitted in the source. | +| `r` | `redactable` | Whether the payload is redactable (see below for details). | +| `t` | `timestamp` | The timestamp at which the event was emitted on the logging channel. | +| `v` | `version` | The binary version with which the event was generated. | + + +After a couple of *header* entries written at the beginning of each log sink, +all subsequent log entries also contain the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `C` | `channel` | The name of the logging channel where the event was sent. | +| `sev` | `severity` | The severity of the event. | +| `c` | `channel_numeric` | The numeric identifier for the logging channel where the event was sent. | +| `n` | `entry_counter` | The entry number on this logging sink, relative to the last process restart. | +| `s` | `severity_numeric` | The numeric value of the severity of the event. | + + +Additionally, the following fields are conditionally present: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `N` | `node_id` | The node ID where the event was generated, once known. Only reported for single-tenant or KV servers. | +| `x` | `cluster_id` | The cluster ID where the event was generated, once known. Only reported for single-tenant of KV servers. | +| `q` | `instance_id` | The SQL instance ID where the event was generated, once known. | +| `T` | `tenant_id` | The SQL tenant ID where the event was generated, once known. | +| `V` | `tenant_name` | The SQL virtual cluster where the event was generated, once known. | +| `tags` | `tags` | The logging context tags for the entry, if there were context tags. | +| `message` | `message` | For unstructured events, the flat text payload. | +| `event` | `event` | The logging event, if structured (see below for details). | +| `stacks` | `stacks` | Goroutine stacks, for fatal events. | + +When an entry is structured, the `event` field maps to a dictionary +whose structure is one of the documented structured events. See the [reference documentation](eventlog.html) +for structured events for a list of possible payloads. + +When the entry is marked as `redactable`, the `tags`, `message`, and/or `event` payloads +contain delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `datetime-format` | The format to use for the `datetime` field. The value can be one of `none`, `iso8601`/`rfc3339` (synonyms), or `rfc1123`. Default is `none`. | +| `datetime-timezone` | The timezone to use for the `datetime` field. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | +| `tag-style` | The tags to include in the envelope. The value can be `compact` (one letter tags) or `verbose` (long-form tags). Default is `verbose`. | +| `fluent-tag` | Whether to produce an additional field called `tag` for Fluent compatibility. Default is `false`. | + + + +## Format `json-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: false` +- `tag-style: compact` + + +## Format `json-fluent` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: verbose` + + +## Format `json-fluent-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: compact` + + diff --git a/src/current/_includes/cockroach-generated/release-24.2/logging.md b/src/current/_includes/cockroach-generated/release-24.2/logging.md new file mode 100644 index 00000000000..8b628dc2dd9 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.2/logging.md @@ -0,0 +1,179 @@ +## Logging levels (severities) + +### INFO + +The `INFO` severity is used for informational messages that do not +require action. + +### WARNING + +The `WARNING` severity is used for situations which may require special handling, +where normal operation is expected to resume automatically. + +### ERROR + +The `ERROR` severity is used for situations that require special handling, +where normal operation could not proceed as expected. +Other operations can continue mostly unaffected. + +### FATAL + +The `FATAL` severity is used for situations that require an immedate, hard +server shutdown. A report is also sent to telemetry if telemetry +is enabled. + + +## Logging channels + +### `DEV` + +The `DEV` channel is used during development to collect log +details useful for troubleshooting that fall outside the +scope of other channels. It is also the default logging +channel for events not associated with a channel. + +This channel is special in that there are no constraints as to +what may or may not be logged on it. Conversely, users in +production deployments are invited to not collect `DEV` logs in +centralized logging facilities, because they likely contain +sensitive operational data. +See [Configure logs](configure-logs.html#dev-channel). + +### `OPS` + +The `OPS` channel is used to report "point" operational events, +initiated by user operators or automation: + + - Operator or system actions on server processes: process starts, + stops, shutdowns, crashes (if they can be logged), + including each time: command-line parameters, current version being run + - Actions that impact the topology of a cluster: node additions, + removals, decommissions, etc. + - Job-related initiation or termination + - [Cluster setting](cluster-settings.html) changes + - [Zone configuration](configure-replication-zones.html) changes + +### `HEALTH` + +The `HEALTH` channel is used to report "background" operational +events, initiated by CockroachDB or reporting on automatic processes: + + - Current resource usage, including critical resource usage + - Node-node connection events, including connection errors and + gossip details + - Range and table leasing events + - Up- and down-replication, range unavailability + +### `STORAGE` + +The `STORAGE` channel is used to report low-level storage +layer events (RocksDB/Pebble). + +### `SESSIONS` + +The `SESSIONS` channel is used to report client network activity when enabled via +the `server.auth_log.sql_connections.enabled` and/or +`server.auth_log.sql_sessions.enabled` [cluster setting](cluster-settings.html): + + - Connections opened/closed + - Authentication events: logins, failed attempts + - Session and query cancellation + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_SCHEMA` + +The `SQL_SCHEMA` channel is used to report changes to the +SQL logical schema, excluding privilege and ownership changes +(which are reported separately on the `PRIVILEGES` channel) and +zone configuration changes (which go to the `OPS` channel). + +This includes: + + - Database/schema/table/sequence/view/type creation + - Adding/removing/changing table columns + - Changing sequence parameters + +`SQL_SCHEMA` events generally comprise changes to the schema that affect the +functional behavior of client apps using stored objects. + +### `USER_ADMIN` + +The `USER_ADMIN` channel is used to report changes +in users and roles, including: + + - Users added/dropped + - Changes to authentication credentials (e.g., passwords, validity, etc.) + - Role grants/revocations + - Role option grants/revocations + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `PRIVILEGES` + +The `PRIVILEGES` channel is used to report data +authorization changes, including: + + - Privilege grants/revocations on database, objects, etc. + - Object ownership changes + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SENSITIVE_ACCESS` + +The `SENSITIVE_ACCESS` channel is used to report SQL +data access to sensitive data: + + - Data access audit events (when table audit is enabled via + [ALTER TABLE ... EXPERIMENTAL_AUDIT](alter-table.html#experimental_audit)) + - Data access audit events (when role-based audit is enabled via + [`sql.log.user_audit` cluster setting](role-based-audit-logging.html#syntax-of-audit-settings)) + - SQL statements executed by users with the admin role + - Operations that write to system tables + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_EXEC` + +The `SQL_EXEC` channel is used to report SQL execution on +behalf of client connections: + + - Logical SQL statement executions (when enabled via the + `sql.log.all_statements.enabled` [cluster setting](cluster-settings.html)) + - uncaught Go panic errors during the execution of a SQL statement. + +### `SQL_PERF` + +The `SQL_PERF` channel is used to report SQL executions +that are marked as "out of the ordinary" +to facilitate performance investigations. +This includes the SQL "slow query log". + +Arguably, this channel overlaps with `SQL_EXEC`. +However, we keep both channels separate for backward compatibility +with versions prior to v21.1, where the corresponding events +were redirected to separate files. + +### `SQL_INTERNAL_PERF` + +The `SQL_INTERNAL_PERF` channel is like the `SQL_PERF` channel, but is aimed at +helping developers of CockroachDB itself. It exists as a separate +channel so as to not pollute the `SQL_PERF` logging output with +internal troubleshooting details. + +### `TELEMETRY` + +The `TELEMETRY` channel reports telemetry events. Telemetry events describe +feature usage within CockroachDB and anonymizes any application- +specific data. + +### `KV_DISTRIBUTION` + +The `KV_DISTRIBUTION` channel is used to report data distribution events, such as moving +replicas between stores in the cluster, or adding (removing) replicas to +ranges. + diff --git a/src/current/_includes/cockroach-generated/release-24.2/settings/settings.html b/src/current/_includes/cockroach-generated/release-24.2/settings/settings.html new file mode 100644 index 00000000000..d848f855e51 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.2/settings/settings.html @@ -0,0 +1,315 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingTypeDefaultDescriptionSupported Deployments
admission.disk_bandwidth_tokens.elastic.enabled
booleantruewhen true, and provisioned bandwidth for the disk corresponding to a store is configured, tokens for elastic work will be limited if disk bandwidth becomes a bottleneckDedicated/Self-Hosted
admission.epoch_lifo.enabled
booleanfalsewhen true, epoch-LIFO behavior is enabled when there is significant delay in admissionServerless/Dedicated/Self-Hosted
admission.epoch_lifo.epoch_closing_delta_duration
duration5msthe delta duration before closing an epoch, for epoch-LIFO admission control orderingServerless/Dedicated/Self-Hosted
admission.epoch_lifo.epoch_duration
duration100msthe duration of an epoch, for epoch-LIFO admission control orderingServerless/Dedicated/Self-Hosted
admission.epoch_lifo.queue_delay_threshold_to_switch_to_lifo
duration105msthe queue delay encountered by a (tenant,priority) for switching to epoch-LIFO orderingServerless/Dedicated/Self-Hosted
admission.kv.enabled
booleantruewhen true, work performed by the KV layer is subject to admission controlDedicated/Self-Hosted
admission.sql_kv_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a KV response is subject to admission controlServerless/Dedicated/Self-Hosted
admission.sql_sql_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a DistSQL response is subject to admission controlServerless/Dedicated/Self-Hosted
bulkio.backup.deprecated_full_backup_with_subdir.enabled
booleanfalsewhen true, a backup command with a user specified subdirectory will create a full backup at the subdirectory if no backup already exists at that subdirectoryServerless/Dedicated/Self-Hosted
bulkio.backup.file_size
byte size128 MiBtarget size for individual data files produced during BACKUPServerless/Dedicated/Self-Hosted
bulkio.backup.read_timeout
duration5m0samount of time after which a read attempt is considered timed out, which causes the backup to failServerless/Dedicated/Self-Hosted
bulkio.backup.read_with_priority_after
duration1m0samount of time since the read-as-of time above which a BACKUP should use priority when retrying readsServerless/Dedicated/Self-Hosted
physical_replication.consumer.minimum_flush_interval
(alias: bulkio.stream_ingestion.minimum_flush_interval)
duration5sthe minimum timestamp between flushes; flushes may still occur if internal buffers fill upDedicated/Self-Hosted
changefeed.aggregator.flush_jitter
float0.1jitter aggregator flushes as a fraction of min_checkpoint_frequency. This setting has no effect if min_checkpoint_frequency is set to 0.Serverless/Dedicated/Self-Hosted
changefeed.backfill.concurrent_scan_requests
integer0number of concurrent scan requests per node issued during a backfillServerless/Dedicated/Self-Hosted
changefeed.backfill.scan_request_size
integer524288the maximum number of bytes returned by each scan requestServerless/Dedicated/Self-Hosted
changefeed.batch_reduction_retry.enabled
(alias: changefeed.batch_reduction_retry_enabled)
booleanfalseif true, kafka changefeeds upon erroring on an oversized batch will attempt to resend the messages with progressively lower batch sizesServerless/Dedicated/Self-Hosted
changefeed.default_range_distribution_strategy
enumerationdefaultconfigures how work is distributed among nodes for a given changefeed. for the most balanced distribution, use `balanced_simple`. changing this setting will not override locality restrictions [default = 0, balanced_simple = 1]Serverless/Dedicated/Self-Hosted
changefeed.event_consumer_worker_queue_size
integer16if changefeed.event_consumer_workers is enabled, this setting sets the maxmimum number of events which a worker can bufferServerless/Dedicated/Self-Hosted
changefeed.event_consumer_workers
integer0the number of workers to use when processing events: <0 disables, 0 assigns a reasonable default, >0 assigns the setting value. for experimental/core changefeeds and changefeeds using parquet format, this is disabledServerless/Dedicated/Self-Hosted
changefeed.fast_gzip.enabled
booleantrueuse fast gzip implementationServerless/Dedicated/Self-Hosted
changefeed.frontier_highwater_lag_checkpoint_threshold
duration10m0scontrols the maximum the high-water mark is allowed to lag behind the leading spans of the frontier before per-span checkpointing is enabled; if 0, checkpointing due to high-water lag is disabledServerless/Dedicated/Self-Hosted
changefeed.memory.per_changefeed_limit
byte size512 MiBcontrols amount of data that can be buffered per changefeedServerless/Dedicated/Self-Hosted
changefeed.min_highwater_advance
duration0sminimum amount of time the changefeed high water mark must advance for it to be eligible for checkpointing; Default of 0 will checkpoint every time frontier advances, as long as the rate of checkpointing keeps up with the rate of frontier changesServerless/Dedicated/Self-Hosted
changefeed.node_throttle_config
stringspecifies node level throttling configuration for all changefeeedsServerless/Dedicated/Self-Hosted
changefeed.protect_timestamp.max_age
duration96h0m0sfail the changefeed if the protected timestamp age exceeds this threshold; 0 disables expirationServerless/Dedicated/Self-Hosted
changefeed.protect_timestamp_interval
duration10m0scontrols how often the changefeed forwards its protected timestamp to the resolved timestampServerless/Dedicated/Self-Hosted
changefeed.schema_feed.read_with_priority_after
duration1m0sretry with high priority if we were not able to read descriptors for too long; 0 disablesServerless/Dedicated/Self-Hosted
changefeed.sink_io_workers
integer0the number of workers used by changefeeds when sending requests to the sink (currently the batching versions of webhook, pubsub, and kafka sinks that are enabled by changefeed.new_<sink type>_sink_enabled only): <0 disables, 0 assigns a reasonable default, >0 assigns the setting valueServerless/Dedicated/Self-Hosted
cloudstorage.azure.concurrent_upload_buffers
integer1controls the number of concurrent buffers that will be used by the Azure client when uploading chunks.Each buffer can buffer up to cloudstorage.write_chunk.size of memory during an uploadServerless/Dedicated/Self-Hosted
cloudstorage.http.custom_ca
stringcustom root CA (appended to system's default CAs) for verifying certificates when interacting with HTTPS storageServerless/Dedicated/Self-Hosted
cloudstorage.timeout
duration10m0sthe timeout for import/export storage operationsServerless/Dedicated/Self-Hosted
cluster.auto_upgrade.enabled
booleantruedisable automatic cluster version upgrade until resetServerless/Dedicated/Self-Hosted
cluster.organization
stringorganization nameDedicated/Self-hosted (read-write); Serverless (read-only)
cluster.preserve_downgrade_option
stringdisable (automatic or manual) cluster version upgrade from the specified version until resetServerless/Dedicated/Self-Hosted
debug.zip.redact_addresses.enabled
booleanfalseenables the redaction of hostnames and ip addresses in debug zipServerless/Dedicated/Self-Hosted
diagnostics.active_query_dumps.enabled
booleantrueexperimental: enable dumping of anonymized active queries to disk when node is under memory pressureDedicated/Self-hosted (read-write); Serverless (read-only)
diagnostics.forced_sql_stat_reset.interval
duration2h0m0sinterval after which the reported SQL Stats are reset even if not collected by telemetry reporter. It has a max value of 24H.Serverless/Dedicated/Self-Hosted
diagnostics.memory_monitoring_dumps.enabled
booleantrueenable dumping of memory monitoring state at the same time as heap profiles are takenDedicated/Self-hosted (read-write); Serverless (read-only)
diagnostics.reporting.enabled
booleantrueenable reporting diagnostic metrics to cockroach labs, but is ignored for Trial or Free licensesServerless/Dedicated/Self-Hosted
diagnostics.reporting.interval
duration1h0m0sinterval at which diagnostics data should be reportedServerless/Dedicated/Self-Hosted
enterprise.license
stringthe encoded cluster licenseDedicated/Self-hosted (read-write); Serverless (read-only)
external.graphite.endpoint
stringif nonempty, push server metrics to the Graphite or Carbon server at the specified host:portServerless/Dedicated/Self-Hosted
external.graphite.interval
duration10sthe interval at which metrics are pushed to Graphite (if enabled)Serverless/Dedicated/Self-Hosted
feature.backup.enabled
booleantrueset to true to enable backups, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.changefeed.enabled
booleantrueset to true to enable changefeeds, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.export.enabled
booleantrueset to true to enable exports, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.import.enabled
booleantrueset to true to enable imports, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.restore.enabled
booleantrueset to true to enable restore, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.schema_change.enabled
booleantrueset to true to enable schema changes, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.stats.enabled
booleantrueset to true to enable CREATE STATISTICS/ANALYZE, false to disable; default is trueServerless/Dedicated/Self-Hosted
jobs.retention_time
duration336h0m0sthe amount of time for which records for completed jobs are retainedServerless/Dedicated/Self-Hosted
kv.allocator.lease_rebalance_threshold
float0.05minimum fraction away from the mean a store's lease count can be before it is considered for lease-transfersDedicated/Self-Hosted
kv.allocator.load_based_lease_rebalancing.enabled
booleantrueset to enable rebalancing of range leases based on load and latencyDedicated/Self-Hosted
kv.allocator.load_based_rebalancing
enumerationleases and replicaswhether to rebalance based on the distribution of load across stores [off = 0, leases = 1, leases and replicas = 2]Dedicated/Self-Hosted
kv.allocator.load_based_rebalancing.objective
enumerationcpuwhat objective does the cluster use to rebalance; if set to `qps` the cluster will attempt to balance qps among stores, if set to `cpu` the cluster will attempt to balance cpu usage among stores [qps = 0, cpu = 1]Dedicated/Self-Hosted
kv.allocator.load_based_rebalancing_interval
duration1m0sthe rough interval at which each store will check for load-based lease / replica rebalancing opportunitiesDedicated/Self-Hosted
kv.allocator.qps_rebalance_threshold
float0.1minimum fraction away from the mean a store's QPS (such as queries per second) can be before it is considered overfull or underfullDedicated/Self-Hosted
kv.allocator.range_rebalance_threshold
float0.05minimum fraction away from the mean a store's range count can be before it is considered overfull or underfullDedicated/Self-Hosted
kv.allocator.store_cpu_rebalance_threshold
float0.1minimum fraction away from the mean a store's cpu usage can be before it is considered overfull or underfullDedicated/Self-Hosted
kv.bulk_io_write.max_rate
byte size1.0 TiBthe rate limit (bytes/sec) to use for writes to disk on behalf of bulk io opsDedicated/Self-Hosted
kv.bulk_sst.max_allowed_overage
byte size64 MiBif positive, allowed size in excess of target size for SSTs from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryDedicated/Self-Hosted
kv.bulk_sst.target_size
byte size16 MiBtarget size for SSTs emitted from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryDedicated/Self-hosted (read-write); Serverless (read-only)
kv.closed_timestamp.follower_reads.enabled
(alias: kv.closed_timestamp.follower_reads_enabled)
booleantrueallow (all) replicas to serve consistent historical reads based on closed timestamp informationDedicated/Self-hosted (read-write); Serverless (read-only)
kv.closed_timestamp.lead_for_global_reads_override
duration0sif nonzero, overrides the lead time that global_read ranges use to publish closed timestampsDedicated/Self-hosted (read-write); Serverless (read-only)
kv.closed_timestamp.side_transport_interval
duration200msthe interval at which the closed timestamp side-transport attempts to advance each range's closed timestamp; set to 0 to disable the side-transportDedicated/Self-hosted (read-write); Serverless (read-only)
kv.closed_timestamp.target_duration
duration3sif nonzero, attempt to provide closed timestamp notifications for timestamps trailing cluster time by approximately this durationDedicated/Self-hosted (read-write); Serverless (read-only)
kv.dist_sender.circuit_breaker.cancellation.enabled
booleantruewhen enabled, in-flight requests will be cancelled when the circuit breaker tripsServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.cancellation.write_grace_period
duration10show long after the circuit breaker trips to cancel write requests (these can't retry internally, so should be long enough to allow quorum/lease recovery)Serverless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.probe.interval
duration3sinterval between replica probesServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.probe.threshold
duration3sduration of errors or stalls after which a replica will be probedServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.probe.timeout
duration3stimeout for replica probesServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breakers.mode
enumerationliveness range onlyset of ranges to trip circuit breakers for failing or stalled replicas [no ranges = 0, liveness range only = 1, all ranges = 2]Serverless/Dedicated/Self-Hosted
kv.lease_transfer_read_summary.global_budget
byte size0 Bcontrols the maximum number of bytes that will be used to summarize the global segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Dedicated/Self-Hosted
kv.lease_transfer_read_summary.local_budget
byte size4.0 MiBcontrols the maximum number of bytes that will be used to summarize the local segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Dedicated/Self-Hosted
kv.log_range_and_node_events.enabled
booleantrueset to true to transactionally log range events (e.g., split, merge, add/remove voter/non-voter) into system.rangelogand node join and restart events into system.eventologDedicated/Self-Hosted
kv.protectedts.reconciliation.interval
duration5m0sthe frequency for reconciling jobs with protected timestamp recordsDedicated/Self-hosted (read-write); Serverless (read-only)
kv.range_split.by_load.enabled
(alias: kv.range_split.by_load_enabled)
booleantrueallow automatic splits of ranges based on where load is concentratedDedicated/Self-Hosted
kv.range_split.load_cpu_threshold
duration500msthe CPU use per second over which, the range becomes a candidate for load based splittingDedicated/Self-Hosted
kv.range_split.load_qps_threshold
integer2500the QPS over which, the range becomes a candidate for load based splittingDedicated/Self-Hosted
kv.rangefeed.client.stream_startup_rate
integer100controls the rate per second the client will initiate new rangefeed stream for a single range; 0 implies unlimitedServerless/Dedicated/Self-Hosted
kv.rangefeed.closed_timestamp_refresh_interval
duration3sthe interval at which closed-timestamp updatesare delivered to rangefeeds; set to 0 to use kv.closed_timestamp.side_transport_intervalDedicated/Self-hosted (read-write); Serverless (read-only)
kv.rangefeed.enabled
booleanfalseif set, rangefeed registration is enabledDedicated/Self-hosted (read-write); Serverless (read-only)
kv.replica_circuit_breaker.slow_replication_threshold
duration1m0sduration after which slow proposals trip the per-Replica circuit breaker (zero duration disables breakers)Dedicated/Self-Hosted
kv.replica_stats.addsst_request_size_factor
integer50000the divisor that is applied to addsstable request sizes, then recorded in a leaseholders QPS; 0 means all requests are treated as cost 1Dedicated/Self-Hosted
kv.replication_reports.interval
duration1m0sthe frequency for generating the replication_constraint_stats, replication_stats_report and replication_critical_localities reports (set to 0 to disable)Dedicated/Self-Hosted
kv.snapshot_rebalance.max_rate
byte size32 MiBthe rate limit (bytes/sec) to use for rebalance and upreplication snapshotsDedicated/Self-Hosted
kv.snapshot_receiver.excise.enabled
booleantrueset to false to disable excises in place of range deletions for KV snapshotsDedicated/Self-Hosted
kv.transaction.max_intents_and_locks
integer0maximum count of inserts or durable locks for a single transactions, 0 to disableServerless/Dedicated/Self-Hosted
kv.transaction.max_intents_bytes
integer4194304maximum number of bytes used to track locks in transactionsServerless/Dedicated/Self-Hosted
kv.transaction.max_refresh_spans_bytes
integer4194304maximum number of bytes used to track refresh spans in serializable transactionsServerless/Dedicated/Self-Hosted
kv.transaction.randomized_anchor_key.enabled
booleanfalsedictates whether a transactions anchor key is randomized or notServerless/Dedicated/Self-Hosted
kv.transaction.reject_over_max_intents_budget.enabled
booleanfalseif set, transactions that exceed their lock tracking budget (kv.transaction.max_intents_bytes) are rejected instead of having their lock spans imprecisely compressedServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.locking_reads.enabled
booleantrueif enabled, transactional locking reads are pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.ranged_writes.enabled
booleantrueif enabled, transactional ranged writes are pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.enabled
(alias: kv.transaction.write_pipelining_enabled)
booleantrueif enabled, transactional writes are pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.max_batch_size
(alias: kv.transaction.write_pipelining_max_batch_size)
integer128if non-zero, defines that maximum size batch that will be pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kvadmission.store.provisioned_bandwidth
byte size0 Bif set to a non-zero value, this is used as the provisioned bandwidth (in bytes/s), for each store. It can be overridden on a per-store basis using the --store flag. Note that setting the provisioned bandwidth to a positive value may enable disk bandwidth based admission control, since admission.disk_bandwidth_tokens.elastic.enabled defaults to trueDedicated/Self-Hosted
schedules.backup.gc_protection.enabled
booleantrueenable chaining of GC protection across backups run as part of a scheduleServerless/Dedicated/Self-Hosted
security.client_cert.subject_required.enabled
booleanfalsemandates a requirement for subject role to be set for db userDedicated/Self-hosted (read-write); Serverless (read-only)
security.ocsp.mode
enumerationoffuse OCSP to check whether TLS certificates are revoked. If the OCSP server is unreachable, in strict mode all certificates will be rejected and in lax mode all certificates will be accepted. [off = 0, lax = 1, strict = 2]Serverless/Dedicated/Self-Hosted
security.ocsp.timeout
duration3stimeout before considering the OCSP server unreachableServerless/Dedicated/Self-Hosted
server.auth_log.sql_connections.enabled
booleanfalseif set, log SQL client connect and disconnect events to the SESSIONS log channel (note: may hinder performance on loaded nodes)Serverless/Dedicated/Self-Hosted
server.auth_log.sql_sessions.enabled
booleanfalseif set, log verbose SQL session authentication events to the SESSIONS log channel (note: may hinder performance on loaded nodes). Session start and end events are always logged regardless of this setting; disable the SESSIONS log channel to suppress them.Serverless/Dedicated/Self-Hosted
server.authentication_cache.enabled
booleantrueenables a cache used during authentication to avoid lookups to system tables when retrieving per-user authentication-related informationServerless/Dedicated/Self-Hosted
server.child_metrics.enabled
booleanfalseenables the exporting of child metrics, additional prometheus time series with extra labelsServerless/Dedicated/Self-Hosted
server.client_cert_expiration_cache.capacity
integer1000the maximum number of client cert expirations storedServerless/Dedicated/Self-Hosted
server.clock.forward_jump_check.enabled
(alias: server.clock.forward_jump_check_enabled)
booleanfalseif enabled, forward clock jumps > max_offset/2 will cause a panicServerless/Dedicated/Self-Hosted
server.clock.persist_upper_bound_interval
duration0sthe interval between persisting the wall time upper bound of the clock. The clock does not generate a wall time greater than the persisted timestamp and will panic if it sees a wall time greater than this value. When cockroach starts, it waits for the wall time to catch-up till this persisted timestamp. This guarantees monotonic wall time across server restarts. Not setting this or setting a value of 0 disables this feature.Serverless/Dedicated/Self-Hosted
server.consistency_check.max_rate
byte size8.0 MiBthe rate limit (bytes/sec) to use for consistency checks; used in conjunction with server.consistency_check.interval to control the frequency of consistency checks. Note that setting this too high can negatively impact performance.Dedicated/Self-Hosted
server.eventlog.enabled
booleantrueif set, logged notable events are also stored in the table system.eventlogServerless/Dedicated/Self-Hosted
server.eventlog.ttl
duration2160h0m0sif nonzero, entries in system.eventlog older than this duration are periodically purgedServerless/Dedicated/Self-Hosted
server.host_based_authentication.configuration
stringhost-based authentication configuration to use during connection authenticationServerless/Dedicated/Self-Hosted
server.hot_ranges_request.node.timeout
duration5m0sthe duration allowed for a single node to return hot range data before the request is cancelled; if set to 0, there is no timeoutServerless/Dedicated/Self-Hosted
server.hsts.enabled
booleanfalseif true, HSTS headers will be sent along with all HTTP requests. The headers will contain a max-age setting of one year. Browsers honoring the header will always use HTTPS to access the DB Console. Ensure that TLS is correctly configured prior to enabling.Serverless/Dedicated/Self-Hosted
server.http.base_path
string/path to redirect the user to upon succcessful loginServerless/Dedicated/Self-Hosted
server.identity_map.configuration
stringsystem-identity to database-username mappingsServerless/Dedicated/Self-Hosted
server.log_gc.max_deletions_per_cycle
integer1000the maximum number of entries to delete on each purge of log-like system tablesServerless/Dedicated/Self-Hosted
server.log_gc.period
duration1h0m0sthe period at which log-like system tables are checked for old entriesServerless/Dedicated/Self-Hosted
server.max_connections_per_gateway
integer-1the maximum number of SQL connections per gateway allowed at a given time (note: this will only limit future connection attempts and will not affect already established connections). Negative values result in unlimited number of connections. Superusers are not affected by this limit.Serverless/Dedicated/Self-Hosted
server.max_open_transactions_per_gateway
integer-1the maximum number of open SQL transactions per gateway allowed at a given time. Negative values result in unlimited number of connections. Superusers are not affected by this limit.Serverless/Dedicated/Self-Hosted
server.oidc_authentication.autologin.enabled
(alias: server.oidc_authentication.autologin)
booleanfalseif true, logged-out visitors to the DB Console will be automatically redirected to the OIDC login endpointServerless/Dedicated/Self-Hosted
server.oidc_authentication.button_text
stringLog in with your OIDC providertext to show on button on DB Console login page to login with your OIDC provider (only shown if OIDC is enabled)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.claim_json_key
stringsets JSON key of principal to extract from payload after OIDC authentication completes (usually email or sid)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.client.timeout
duration30ssets the client timeout for external calls made during OIDC authentication (e.g. authorization code flow, etc.)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.client_id
stringsets OIDC client idServerless/Dedicated/Self-Hosted
server.oidc_authentication.client_secret
stringsets OIDC client secretServerless/Dedicated/Self-Hosted
server.oidc_authentication.enabled
booleanfalseenables or disabled OIDC login for the DB ConsoleServerless/Dedicated/Self-Hosted
server.oidc_authentication.principal_regex
string(.+)regular expression to apply to extracted principal (see claim_json_key setting) to translate to SQL user (golang regex format, must include 1 grouping to extract)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.provider_url
stringsets OIDC provider URL ({provider_url}/.well-known/openid-configuration must resolve)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.redirect_url
stringhttps://localhost:8080/oidc/v1/callbacksets OIDC redirect URL via a URL string or a JSON string containing a required `redirect_urls` key with an object that maps from region keys to URL strings (URLs should point to your load balancer and must route to the path /oidc/v1/callback)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.scopes
stringopenidsets OIDC scopes to include with authentication request (space delimited list of strings, required to start with `openid`)Serverless/Dedicated/Self-Hosted
server.rangelog.ttl
duration720h0m0sif nonzero, entries in system.rangelog older than this duration are periodically purgedDedicated/Self-Hosted
server.redact_sensitive_settings.enabled
booleanfalseenables or disables the redaction of sensitive settings in the output of SHOW CLUSTER SETTINGS and SHOW ALL CLUSTER SETTINGS for users without the MODIFYCLUSTERSETTING privilegeServerless/Dedicated/Self-Hosted
server.shutdown.connections.timeout
(alias: server.shutdown.connection_wait)
duration0sthe maximum amount of time a server waits for all SQL connections to be closed before proceeding with a drain. (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Serverless/Dedicated/Self-Hosted
server.shutdown.initial_wait
(alias: server.shutdown.drain_wait)
duration0sthe amount of time a server waits in an unready state before proceeding with a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting. --drain-wait is to specify the duration of the whole draining process, while server.shutdown.initial_wait is to set the wait time for health probes to notice that the node is not ready.)Serverless/Dedicated/Self-Hosted
server.shutdown.lease_transfer_iteration.timeout
(alias: server.shutdown.lease_transfer_wait)
duration5sthe timeout for a single iteration of the range lease transfer phase of draining (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Dedicated/Self-Hosted
server.shutdown.transactions.timeout
(alias: server.shutdown.query_wait)
duration10sthe timeout for waiting for active transactions to finish during a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Serverless/Dedicated/Self-Hosted
server.sql_tcp_keep_alive.count
integer3maximum number of probes that will be sent out before a connection is dropped because it's unresponsive (Linux and Darwin only)Serverless/Dedicated/Self-Hosted
server.sql_tcp_keep_alive.interval
duration10stime between keep alive probes and idle time before probes are sent outServerless/Dedicated/Self-Hosted
server.time_until_store_dead
duration5m0sthe time after which if there is no new gossiped information about a store, it is considered deadServerless/Dedicated/Self-Hosted
server.user_login.cert_password_method.auto_scram_promotion.enabled
booleantruewhether to automatically promote cert-password authentication to use SCRAMServerless/Dedicated/Self-Hosted
server.user_login.downgrade_scram_stored_passwords_to_bcrypt.enabled
booleantrueif server.user_login.password_encryption=crdb-bcrypt, this controls whether to automatically re-encode stored passwords using scram-sha-256 to crdb-bcryptServerless/Dedicated/Self-Hosted
server.user_login.min_password_length
integer1the minimum length accepted for passwords set in cleartext via SQL. Note that a value lower than 1 is ignored: passwords cannot be empty in any case. This setting only applies when adding new users or altering an existing user's password; it will not affect existing logins.Serverless/Dedicated/Self-Hosted
server.user_login.password_encryption
enumerationscram-sha-256which hash method to use to encode cleartext passwords passed via ALTER/CREATE USER/ROLE WITH PASSWORD [crdb-bcrypt = 2, scram-sha-256 = 3]Serverless/Dedicated/Self-Hosted
server.user_login.password_hashes.default_cost.crdb_bcrypt
integer10the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method crdb-bcrypt (allowed range: 4-31)Serverless/Dedicated/Self-Hosted
server.user_login.password_hashes.default_cost.scram_sha_256
integer10610the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method scram-sha-256 (allowed range: 4096-240000000000)Serverless/Dedicated/Self-Hosted
server.user_login.rehash_scram_stored_passwords_on_cost_change.enabled
booleantrueif server.user_login.password_hashes.default_cost.scram_sha_256 differs from, the cost in a stored hash, this controls whether to automatically re-encode stored passwords using scram-sha-256 with the new default costServerless/Dedicated/Self-Hosted
server.user_login.timeout
duration10stimeout after which client authentication times out if some system range is unavailable (0 = no timeout)Serverless/Dedicated/Self-Hosted
server.user_login.upgrade_bcrypt_stored_passwords_to_scram.enabled
booleantrueif server.user_login.password_encryption=scram-sha-256, this controls whether to automatically re-encode stored passwords using crdb-bcrypt to scram-sha-256Serverless/Dedicated/Self-Hosted
server.web_session.purge.ttl
duration1h0m0sif nonzero, entries in system.web_sessions older than this duration are periodically purgedServerless/Dedicated/Self-Hosted
server.web_session.timeout
(alias: server.web_session_timeout)
duration168h0m0sthe duration that a newly created web session will be validServerless/Dedicated/Self-Hosted
spanconfig.bounds.enabled
booleantruedictates whether span config bounds are consulted when serving span configs for secondary tenantsDedicated/Self-Hosted
spanconfig.range_coalescing.system.enabled
(alias: spanconfig.storage_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs, for the ranges specific to the system tenantDedicated/Self-Hosted
spanconfig.range_coalescing.application.enabled
(alias: spanconfig.tenant_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs across all secondary tenant keyspacesDedicated/Self-Hosted
sql.auth.change_own_password.enabled
booleanfalsecontrols whether a user is allowed to change their own password, even if they have no other privilegesServerless/Dedicated/Self-Hosted
sql.auth.grant_option_for_owner.enabled
booleantruedetermines whether the GRANT OPTION for privileges is implicitly given to the owner of an objectServerless/Dedicated/Self-Hosted
sql.auth.grant_option_inheritance.enabled
booleantruedetermines whether the GRANT OPTION for privileges is inherited through role membershipServerless/Dedicated/Self-Hosted
sql.auth.public_schema_create_privilege.enabled
booleantruedetermines whether to grant all users the CREATE privileges on the public schema when it is createdServerless/Dedicated/Self-Hosted
sql.closed_session_cache.capacity
integer1000the maximum number of sessions in the cacheServerless/Dedicated/Self-Hosted
sql.closed_session_cache.time_to_live
integer3600the maximum time to live, in secondsServerless/Dedicated/Self-Hosted
sql.contention.event_store.capacity
byte size64 MiBthe in-memory storage capacity per-node of contention event storeServerless/Dedicated/Self-Hosted
sql.contention.event_store.duration_threshold
duration0sminimum contention duration to cause the contention events to be collected into crdb_internal.transaction_contention_eventsServerless/Dedicated/Self-Hosted
sql.contention.record_serialization_conflicts.enabled
booleantrueenables recording 40001 errors with conflicting txn meta as SERIALIZATION_CONFLICTcontention events into crdb_internal.transaction_contention_eventsServerless/Dedicated/Self-Hosted
sql.contention.txn_id_cache.max_size
byte size64 MiBthe maximum byte size TxnID cache will use (set to 0 to disable)Serverless/Dedicated/Self-Hosted
sql.cross_db_fks.enabled
booleanfalseif true, creating foreign key references across databases is allowedServerless/Dedicated/Self-Hosted
sql.cross_db_sequence_owners.enabled
booleanfalseif true, creating sequences owned by tables from other databases is allowedServerless/Dedicated/Self-Hosted
sql.cross_db_sequence_references.enabled
booleanfalseif true, sequences referenced by tables from other databases are allowedServerless/Dedicated/Self-Hosted
sql.cross_db_views.enabled
booleanfalseif true, creating views that refer to other databases is allowedServerless/Dedicated/Self-Hosted
sql.defaults.cost_scans_with_default_col_size.enabled
booleanfalsesetting to true uses the same size for all columns to compute scan cost
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.datestyle
enumerationiso, mdydefault value for DateStyle session setting [iso, mdy = 0, iso, dmy = 1, iso, ymd = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.default_hash_sharded_index_bucket_count
integer16used as bucket count if bucket count is not specified in hash sharded index definition
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.default_int_size
integer8the size, in bytes, of an INT type
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.disallow_full_table_scans.enabled
booleanfalsesetting to true rejects queries that have planned a full table scan
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.distsql
enumerationautodefault distributed SQL execution mode [off = 0, auto = 1, on = 2, always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_alter_column_type.enabled
booleanfalsedefault value for experimental_alter_column_type session setting; enables the use of ALTER COLUMN TYPE for general conversions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_distsql_planning
enumerationoffdefault experimental_distsql_planning mode; enables experimental opt-driven DistSQL planning [off = 0, on = 1]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_enable_unique_without_index_constraints.enabled
booleanfalsedefault value for experimental_enable_unique_without_index_constraints session setting;disables unique without index constraints by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_implicit_column_partitioning.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for the use of implicit column partitioning
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_temporary_tables.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for use of temporary tables by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.foreign_key_cascades_limit
integer10000default value for foreign_key_cascades_limit session setting; limits the number of cascading operations that run as part of a single query
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.idle_in_session_timeout
duration0sdefault value for the idle_in_session_timeout; default value for the idle_in_session_timeout session setting; controls the duration a session is permitted to idle before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.idle_in_transaction_session_timeout
duration0sdefault value for the idle_in_transaction_session_timeout; controls the duration a session is permitted to idle in a transaction before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.implicit_select_for_update.enabled
booleantruedefault value for enable_implicit_select_for_update session setting; enables FOR UPDATE locking during the row-fetch phase of mutation statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.insert_fast_path.enabled
booleantruedefault value for enable_insert_fast_path session setting; enables a specialized insert path
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.intervalstyle
enumerationpostgresdefault value for IntervalStyle session setting [postgres = 0, iso_8601 = 1, sql_standard = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.large_full_scan_rows
float1000default value for large_full_scan_rows session setting which determines the maximum table size allowed for a full scan when disallow_full_table_scans is set to true
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.locality_optimized_partitioned_index_scan.enabled
booleantruedefault value for locality_optimized_partitioned_index_scan session setting; enables searching for rows in the current region before searching remote regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.lock_timeout
duration0sdefault value for the lock_timeout; default value for the lock_timeout session setting; controls the duration a query is permitted to wait while attempting to acquire a lock on a key or while blocking on an existing lock in order to perform a non-locking read on a key; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.on_update_rehome_row.enabled
booleantruedefault value for on_update_rehome_row; enables ON UPDATE rehome_row() expressions to trigger on updates
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.optimizer_use_histograms.enabled
booleantruedefault value for optimizer_use_histograms session setting; enables usage of histograms in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.optimizer_use_multicol_stats.enabled
booleantruedefault value for optimizer_use_multicol_stats session setting; enables usage of multi-column stats in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.override_alter_primary_region_in_super_region.enabled
booleanfalsedefault value for override_alter_primary_region_in_super_region; allows for altering the primary region even if the primary region is a member of a super region
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.override_multi_region_zone_config.enabled
booleanfalsedefault value for override_multi_region_zone_config; allows for overriding the zone configs of a multi-region table or database
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.prefer_lookup_joins_for_fks.enabled
booleanfalsedefault value for prefer_lookup_joins_for_fks session setting; causes foreign key operations to use lookup joins when possible
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.primary_region
stringif not empty, all databases created without a PRIMARY REGION will implicitly have the given PRIMARY REGION
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.reorder_joins_limit
integer8default number of joins to reorder
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.require_explicit_primary_keys.enabled
booleanfalsedefault value for requiring explicit primary keys in CREATE TABLE statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.results_buffer.size
byte size512 KiBdefault size of the buffer that accumulates results for a statement or a batch of statements before they are sent to the client. This can be overridden on an individual connection with the 'results_buffer_size' parameter. Note that auto-retries generally only happen while no results have been delivered to the client, so reducing this size can increase the number of retriable errors a client receives. On the other hand, increasing the buffer size can increase the delay until the client receives the first result row. Updating the setting only affects new connections. Setting to 0 disables any buffering.
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.serial_normalization
enumerationrowiddefault handling of SERIAL in table definitions [rowid = 0, virtual_sequence = 1, sql_sequence = 2, sql_sequence_cached = 3, unordered_rowid = 4, sql_sequence_cached_node = 5]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.statement_timeout
duration0sdefault value for the statement_timeout; default value for the statement_timeout session setting; controls the duration a query is permitted to run before it is canceled; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.stub_catalog_tables.enabled
booleantruedefault value for stub_catalog_tables session setting
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.super_regions.enabled
booleanfalsedefault value for enable_super_regions; allows for the usage of super regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_read_err
integer0the limit for the number of rows read by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_read_log
integer0the threshold for the number of rows read by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_written_err
integer0the limit for the number of rows written by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_written_log
integer0the threshold for the number of rows written by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.use_declarative_schema_changer
enumerationondefault value for use_declarative_schema_changer session setting;disables new schema changer by default [off = 0, on = 1, unsafe = 2, unsafe_always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.vectorize
enumerationondefault vectorize mode [on = 0, on = 1, on = 2, experimental_always = 3, off = 4]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.zigzag_join.enabled
booleanfalsedefault value for enable_zigzag_join session setting; disallows use of zig-zag join by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.distsql.temp_storage.workmem
byte size64 MiBmaximum amount of memory in bytes a processor can use before falling back to temp storageServerless/Dedicated/Self-Hosted
sql.guardrails.max_row_size_err
byte size512 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an error is returned; use 0 to disableServerless/Dedicated/Self-Hosted
sql.guardrails.max_row_size_log
byte size64 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an event is logged to SQL_PERF (or SQL_INTERNAL_PERF if the mutating statement was internal); use 0 to disableServerless/Dedicated/Self-Hosted
sql.hash_sharded_range_pre_split.max
integer16max pre-split ranges to have when adding hash sharded index to an existing tableServerless/Dedicated/Self-Hosted
sql.index_recommendation.drop_unused_duration
duration168h0m0sthe index unused duration at which we begin to recommend dropping the indexServerless/Dedicated/Self-Hosted
sql.insights.anomaly_detection.enabled
booleantrueenable per-fingerprint latency recording and anomaly detectionServerless/Dedicated/Self-Hosted
sql.insights.anomaly_detection.latency_threshold
duration50msstatements must surpass this threshold to trigger anomaly detection and identificationServerless/Dedicated/Self-Hosted
sql.insights.anomaly_detection.memory_limit
byte size1.0 MiBthe maximum amount of memory allowed for tracking statement latenciesServerless/Dedicated/Self-Hosted
sql.insights.execution_insights_capacity
integer1000the size of the per-node store of execution insightsServerless/Dedicated/Self-Hosted
sql.insights.high_retry_count.threshold
integer10the number of retries a slow statement must have undergone for its high retry count to be highlighted as a potential problemServerless/Dedicated/Self-Hosted
sql.insights.latency_threshold
duration100msamount of time after which an executing statement is considered slow. Use 0 to disable.Serverless/Dedicated/Self-Hosted
sql.log.redact_names.enabled
booleanfalseif set, schema object identifers are redacted in SQL statements that appear in event logsServerless/Dedicated/Self-Hosted
sql.log.slow_query.experimental_full_table_scans.enabled
booleanfalsewhen set to true, statements that perform a full table/index scan will be logged to the slow query log even if they do not meet the latency threshold. Must have the slow query log enabled for this setting to have any effect.Serverless/Dedicated/Self-Hosted
sql.log.slow_query.internal_queries.enabled
booleanfalsewhen set to true, internal queries which exceed the slow query log threshold are logged to a separate log. Must have the slow query log enabled for this setting to have any effect.Serverless/Dedicated/Self-Hosted
sql.log.slow_query.latency_threshold
duration0swhen set to non-zero, log statements whose service latency exceeds the threshold to a secondary logger on each nodeServerless/Dedicated/Self-Hosted
sql.log.user_audit
stringuser/role-based audit logging configuration. An enterprise license is required for this cluster setting to take effect.Serverless/Dedicated/Self-Hosted
sql.log.user_audit.reduced_config.enabled
booleanfalseenables logic to compute a reduced audit configuration, computing the audit configuration only once at session start instead of at each SQL event. The tradeoff with the increase in performance (~5%), is that changes to the audit configuration (user role memberships/cluster setting) are not reflected within session. Users will need to start a new session to see these changes in their auditing behaviour.Serverless/Dedicated/Self-Hosted
sql.metrics.index_usage_stats.enabled
booleantruecollect per index usage statisticsServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_reported_stmt_fingerprints
integer100000the maximum number of reported statement fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_reported_txn_fingerprints
integer100000the maximum number of reported transaction fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_stmt_fingerprints
integer7500the maximum number of statement fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_txn_fingerprints
integer7500the maximum number of transaction fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.dump_to_logs.enabled
(alias: sql.metrics.statement_details.dump_to_logs)
booleanfalsedump collected statement statistics to node logs when periodically clearedServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.enabled
booleantruecollect per-statement query statisticsServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.gateway_node.enabled
booleanfalsesave the gateway node for each statement fingerprint. If false, the value will be stored as 0.Serverless/Dedicated/Self-Hosted
sql.metrics.statement_details.index_recommendation_collection.enabled
booleantruegenerate an index recommendation for each fingerprint IDServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.max_mem_reported_idx_recommendations
integer5000the maximum number of reported index recommendation info stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.plan_collection.enabled
booleanfalseperiodically save a logical plan for each fingerprintServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.plan_collection.period
duration5m0sthe time until a new logical plan is collectedServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.threshold
duration0sminimum execution time to cause statement statistics to be collected. If configured, no transaction stats are collected.Serverless/Dedicated/Self-Hosted
sql.metrics.transaction_details.enabled
booleantruecollect per-application transaction statisticsServerless/Dedicated/Self-Hosted
sql.multiple_modifications_of_table.enabled
booleanfalseif true, allow statements containing multiple INSERT ON CONFLICT, UPSERT, UPDATE, or DELETE subqueries modifying the same table, at the risk of data corruption if the same row is modified multiple times by a single statement (multiple INSERT subqueries without ON CONFLICT cannot cause corruption and are always allowed)Serverless/Dedicated/Self-Hosted
sql.multiregion.drop_primary_region.enabled
booleantrueallows dropping the PRIMARY REGION of a database if it is the last regionServerless/Dedicated/Self-Hosted
sql.notices.enabled
booleantrueenable notices in the server/client protocol being sentServerless/Dedicated/Self-Hosted
sql.optimizer.uniqueness_checks_for_gen_random_uuid.enabled
booleanfalseif enabled, uniqueness checks may be planned for mutations of UUID columns updated with gen_random_uuid(); otherwise, uniqueness is assumed due to near-zero collision probabilityServerless/Dedicated/Self-Hosted
sql.schema.telemetry.recurrence
string@weeklycron-tab recurrence for SQL schema telemetry jobDedicated/Self-hosted (read-write); Serverless (read-only)
sql.spatial.experimental_box2d_comparison_operators.enabled
booleanfalseenables the use of certain experimental box2d comparison operatorsServerless/Dedicated/Self-Hosted
sql.stats.activity.persisted_rows.max
integer200000maximum number of rows of statement and transaction activity that will be persisted in the system tablesServerless/Dedicated/Self-Hosted
sql.stats.automatic_collection.enabled
booleantrueautomatic statistics collection modeServerless/Dedicated/Self-Hosted
sql.stats.automatic_collection.fraction_stale_rows
float0.2target fraction of stale rows per table that will trigger a statistics refreshServerless/Dedicated/Self-Hosted
sql.stats.automatic_collection.min_stale_rows
integer500target minimum number of stale rows per table that will trigger a statistics refreshServerless/Dedicated/Self-Hosted
sql.stats.cleanup.recurrence
string@hourlycron-tab recurrence for SQL Stats cleanup jobServerless/Dedicated/Self-Hosted
sql.stats.flush.enabled
booleantrueif set, SQL execution statistics are periodically flushed to diskServerless/Dedicated/Self-Hosted
sql.stats.flush.interval
duration10m0sthe interval at which SQL execution statistics are flushed to disk, this value must be less than or equal to 1 hourServerless/Dedicated/Self-Hosted
sql.stats.forecasts.enabled
booleantruewhen true, enables generation of statistics forecasts by default for all tablesServerless/Dedicated/Self-Hosted
sql.stats.forecasts.max_decrease
float0.3333333333333333the most a prediction is allowed to decrease, expressed as the minimum ratio of the prediction to the lowest prior observationServerless/Dedicated/Self-Hosted
sql.stats.forecasts.min_goodness_of_fit
float0.95the minimum R² (goodness of fit) measurement required from all predictive models to use a forecastServerless/Dedicated/Self-Hosted
sql.stats.forecasts.min_observations
integer3the mimimum number of observed statistics required to produce a statistics forecastServerless/Dedicated/Self-Hosted
sql.stats.histogram_buckets.count
integer200maximum number of histogram buckets to build during table statistics collectionServerless/Dedicated/Self-Hosted
sql.stats.histogram_collection.enabled
booleantruehistogram collection modeServerless/Dedicated/Self-Hosted
sql.stats.histogram_samples.count
integer0number of rows sampled for histogram construction during table statistics collection. Not setting this or setting a value of 0 means that a reasonable sample size will be automatically picked based on the table size.Serverless/Dedicated/Self-Hosted
sql.stats.multi_column_collection.enabled
booleantruemulti-column statistics collection modeServerless/Dedicated/Self-Hosted
sql.stats.non_default_columns.min_retention_period
duration24h0m0sminimum retention period for table statistics collected on non-default columnsServerless/Dedicated/Self-Hosted
sql.stats.non_indexed_json_histograms.enabled
booleantrueset to true to collect table statistics histograms on non-indexed JSON columnsServerless/Dedicated/Self-Hosted
sql.stats.persisted_rows.max
integer1000000maximum number of rows of statement and transaction statistics that will be persisted in the system tables before compaction beginsServerless/Dedicated/Self-Hosted
sql.stats.post_events.enabled
booleanfalseif set, an event is logged for every CREATE STATISTICS jobServerless/Dedicated/Self-Hosted
sql.stats.response.max
integer20000the maximum number of statements and transaction stats returned in a CombinedStatements requestServerless/Dedicated/Self-Hosted
sql.stats.response.show_internal.enabled
booleanfalsecontrols if statistics for internal executions should be returned by the CombinedStatements and if internal sessions should be returned by the ListSessions endpoints. These endpoints are used to display statistics on the SQL Activity pagesServerless/Dedicated/Self-Hosted
sql.stats.system_tables.enabled
booleantruewhen true, enables use of statistics on system tables by the query optimizerServerless/Dedicated/Self-Hosted
sql.stats.system_tables_autostats.enabled
booleantruewhen true, enables automatic collection of statistics on system tablesServerless/Dedicated/Self-Hosted
sql.stats.virtual_computed_columns.enabled
booleantrueset to true to collect table statistics on virtual computed columnsServerless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.enabled
booleanfalsewhen set to true, executed queries will emit an event on the telemetry logging channelServerless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.internal.enabled
booleanfalsewhen set to true, internal queries will be sampled in telemetry loggingServerless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample executions for telemetry, note that it is recommended that this value shares a log-line limit of 10 logs per second on the telemetry pipeline with all other telemetry events. If sampling mode is set to 'transaction', this value is ignored.Serverless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.mode
enumerationstatementthe execution level used for telemetry sampling. If set to 'statement', events are sampled at the statement execution level. If set to 'transaction', events are sampled at the transaction execution level, i.e. all statements for a transaction will be logged and are counted together as one sampled event (events are still emitted one per statement). [statement = 0, transaction = 1]Serverless/Dedicated/Self-Hosted
sql.telemetry.transaction_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample transactions for telemetry. If sampling mode is set to 'statement', this setting is ignored. In practice, this means that we only sample a transaction if 1/max_event_frequency seconds have elapsed since the last transaction was sampled.Serverless/Dedicated/Self-Hosted
sql.telemetry.transaction_sampling.statement_events_per_transaction.max
integer50the maximum number of statement events to log for every sampled transaction. Note that statements that are logged by force do not adhere to this limit.Serverless/Dedicated/Self-Hosted
sql.temp_object_cleaner.cleanup_interval
duration30m0show often to clean up orphaned temporary objectsServerless/Dedicated/Self-Hosted
sql.temp_object_cleaner.wait_interval
duration30m0show long after creation a temporary object will be cleaned upServerless/Dedicated/Self-Hosted
sql.log.all_statements.enabled
(alias: sql.trace.log_statement_execute)
booleanfalseset to true to enable logging of all executed statementsServerless/Dedicated/Self-Hosted
sql.trace.stmt.enable_threshold
duration0senables tracing on all statements; statements executing for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting applies to individual statements within a transaction and is therefore finer-grained than sql.trace.txn.enable_thresholdServerless/Dedicated/Self-Hosted
sql.trace.txn.enable_threshold
duration0senables tracing on all transactions; transactions open for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting is coarser-grained than sql.trace.stmt.enable_threshold because it applies to all statements within a transaction as well as client communication (e.g. retries)Serverless/Dedicated/Self-Hosted
sql.ttl.changefeed_replication.disabled
booleanfalseif true, deletes issued by TTL will not be replicated via changefeeds (this setting will be ignored by changefeeds that have the ignore_disable_changefeed_replication option set; such changefeeds will continue to replicate all TTL deletes)Serverless/Dedicated/Self-Hosted
sql.ttl.default_delete_batch_size
integer100default amount of rows to delete in a single query during a TTL jobServerless/Dedicated/Self-Hosted
sql.ttl.default_delete_rate_limit
integer100default delete rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Serverless/Dedicated/Self-Hosted
sql.ttl.default_select_batch_size
integer500default amount of rows to select in a single query during a TTL jobServerless/Dedicated/Self-Hosted
sql.ttl.default_select_rate_limit
integer0default select rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Serverless/Dedicated/Self-Hosted
sql.ttl.job.enabled
booleantruewhether the TTL job is enabledServerless/Dedicated/Self-Hosted
sql.txn.read_committed_isolation.enabled
booleantrueset to true to allow transactions to use the READ COMMITTED isolation level if specified by BEGIN/SET commandsServerless/Dedicated/Self-Hosted
sql.txn_fingerprint_id_cache.capacity
integer100the maximum number of txn fingerprint IDs storedServerless/Dedicated/Self-Hosted
storage.experimental.eventually_file_only_snapshots.enabled
booleantrueset to false to disable eventually-file-only-snapshots (kv.snapshot_receiver.excise.enabled must also be false)Dedicated/Self-Hosted
storage.ingest_split.enabled
booleantrueset to false to disable ingest-time splitting that lowers write-amplificationDedicated/Self-Hosted
storage.ingestion.value_blocks.enabled
booleantrueset to true to enable writing of value blocks in ingestion sstablesServerless/Dedicated/Self-Hosted
storage.max_sync_duration
duration20smaximum duration for disk operations; any operations that take longer than this setting trigger a warning log entry or process crashDedicated/Self-hosted (read-write); Serverless (read-only)
storage.max_sync_duration.fatal.enabled
booleantrueif true, fatal the process when a disk operation exceeds storage.max_sync_durationServerless/Dedicated/Self-Hosted
storage.sstable.compression_algorithm
enumerationsnappydetermines the compression algorithm to use when compressing sstable data blocks for use in a Pebble store; [snappy = 1, zstd = 2, none = 3]Dedicated/Self-hosted (read-write); Serverless (read-only)
storage.sstable.compression_algorithm_backup_storage
enumerationsnappydetermines the compression algorithm to use when compressing sstable data blocks for backup row data storage; [snappy = 1, zstd = 2, none = 3]Dedicated/Self-hosted (read-write); Serverless (read-only)
storage.sstable.compression_algorithm_backup_transport
enumerationsnappydetermines the compression algorithm to use when compressing sstable data blocks for backup transport; [snappy = 1, zstd = 2, none = 3]Dedicated/Self-hosted (read-write); Serverless (read-only)
storage.wal_failover.unhealthy_op_threshold
duration100msthe latency of a WAL write considered unhealthy and triggers a failover to a secondary WAL locationDedicated/Self-Hosted
timeseries.storage.enabled
booleantrueif set, periodic timeseries data is stored within the cluster; disabling is not recommended unless you are storing the data elsewhereDedicated/Self-Hosted
timeseries.storage.resolution_10s.ttl
duration240h0m0sthe maximum age of time series data stored at the 10 second resolution. Data older than this is subject to rollup and deletion.Dedicated/Self-hosted (read-write); Serverless (read-only)
timeseries.storage.resolution_30m.ttl
duration2160h0m0sthe maximum age of time series data stored at the 30 minute resolution. Data older than this is subject to deletion.Dedicated/Self-hosted (read-write); Serverless (read-only)
trace.debug_http_endpoint.enabled
(alias: trace.debug.enable)
booleanfalseif set, traces for recent requests can be seen at https://<ui>/debug/requestsServerless/Dedicated/Self-Hosted
trace.opentelemetry.collector
stringaddress of an OpenTelemetry trace collector to receive traces using the otel gRPC protocol, as <host>:<port>. If no port is specified, 4317 will be used.Serverless/Dedicated/Self-Hosted
trace.snapshot.rate
duration0sif non-zero, interval at which background trace snapshots are capturedServerless/Dedicated/Self-Hosted
trace.span_registry.enabled
booleantrueif set, ongoing traces can be seen at https://<ui>/#/debug/tracezServerless/Dedicated/Self-Hosted
trace.zipkin.collector
stringthe address of a Zipkin instance to receive traces, as <host>:<port>. If no port is specified, 9411 will be used.Serverless/Dedicated/Self-Hosted
ui.database_locality_metadata.enabled
booleantrueif enabled shows extended locality data about databases and tables in DB Console which can be expensive to computeServerless/Dedicated/Self-Hosted
ui.display_timezone
enumerationetc/utcthe timezone used to format timestamps in the ui [etc/utc = 0, america/new_york = 1]Serverless/Dedicated/Self-Hosted
version
version24.2set the active cluster version in the format '<major>.<minor>'Serverless/Dedicated/Self-Hosted
diff --git a/src/current/_includes/cockroach-generated/release-24.2/sql/aggregates.md b/src/current/_includes/cockroach-generated/release-24.2/sql/aggregates.md new file mode 100644 index 00000000000..3213f0f02a8 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.2/sql/aggregates.md @@ -0,0 +1,579 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_agg(arg1: bool) → bool[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bool[]) → bool[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes) → bytes[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes[]) → bytes[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date) → date[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date[]) → date[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal) → decimal[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal[]) → decimal[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float) → float[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float[]) → float[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet) → inet[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet[]) → inet[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int) → int[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int[]) → int[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval) → interval[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval[]) → interval[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string) → string[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string[]) → string[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time) → time[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time[]) → time[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp) → timestamp[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp[]) → timestamp[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz) → timestamptz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz[]) → timestamptz[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid) → uuid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid[]) → uuid[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum) → anyenum[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum[]) → anyenum[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d) → box2d[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d[]) → box2d[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography) → geography[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography[]) → geography[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry) → geometry[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry[]) → geometry[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb) → jsonb[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb[]) → jsonb[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid) → oid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid[]) → oid[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn) → pg_lsn[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn[]) → pg_lsn[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor) → refcursor[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor[]) → refcursor[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz) → timetz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz[]) → timetz[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple) → tuple[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple[]) → tuple[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit) → varbit[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit[]) → varbit[][]

Aggregates the selected values into an array.

+		Immutable
array_cat_agg(arg1: bool[]) → bool[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: bytes[]) → bytes[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: date[]) → date[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: decimal[]) → decimal[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: float[]) → float[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: inet[]) → inet[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: int[]) → int[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: interval[]) → interval[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: string[]) → string[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: time[]) → time[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamp[]) → timestamp[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamptz[]) → timestamptz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: uuid[]) → uuid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: anyenum[]) → anyenum[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: box2d[]) → box2d[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geography[]) → geography[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geometry[]) → geometry[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: jsonb[]) → jsonb[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: oid[]) → oid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: pg_lsn[]) → pg_lsn[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: refcursor[]) → refcursor[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timetz[]) → timetz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: tuple[]) → tuple[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: varbit[]) → varbit[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
avg(arg1: decimal) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: float) → float

Calculates the average of the selected values.

+		Immutable
avg(arg1: int) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: interval) → interval

Calculates the average of the selected values.

+		Immutable
bit_and(arg1: int) → int

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_and(arg1: varbit) → varbit

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: int) → int

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: varbit) → varbit

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bool_and(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
bool_or(arg1: bool) → bool

Calculates the boolean value of ORing all selected values.

+		Immutable
concat_agg(arg1: bytes) → bytes

Concatenates all selected values.

+		Immutable
concat_agg(arg1: string) → string

Concatenates all selected values.

+		Immutable
corr(arg1: decimal, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
count(arg1: anyelement) → int

Calculates the number of selected elements.

+		Immutable
count_rows() → int

Calculates the number of rows.

+		Immutable
covar_pop(arg1: decimal, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
every(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
json_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
json_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
jsonb_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
jsonb_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
max(arg1: bool) → bool

Identifies the maximum selected value.

+		Immutable
max(arg1: bytes) → bytes

Identifies the maximum selected value.

+		Immutable
max(arg1: date) → date

Identifies the maximum selected value.

+		Immutable
max(arg1: decimal) → decimal

Identifies the maximum selected value.

+		Immutable
max(arg1: float) → float

Identifies the maximum selected value.

+		Immutable
max(arg1: inet) → inet

Identifies the maximum selected value.

+		Immutable
max(arg1: int) → int

Identifies the maximum selected value.

+		Immutable
max(arg1: interval) → interval

Identifies the maximum selected value.

+		Immutable
max(arg1: string) → string

Identifies the maximum selected value.

+		Immutable
max(arg1: time) → time

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamp) → timestamp

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamptz) → timestamptz

Identifies the maximum selected value.

+		Immutable
max(arg1: uuid) → uuid

Identifies the maximum selected value.

+		Immutable
max(arg1: anyenum) → anyenum

Identifies the maximum selected value.

+		Immutable
max(arg1: box2d) → box2d

Identifies the maximum selected value.

+		Immutable
max(arg1: collatedstring{*}) → collatedstring{*}

Identifies the maximum selected value.

+		Immutable
max(arg1: geography) → geography

Identifies the maximum selected value.

+		Immutable
max(arg1: geometry) → geometry

Identifies the maximum selected value.

+		Immutable
max(arg1: jsonb) → jsonb

Identifies the maximum selected value.

+		Immutable
max(arg1: oid) → oid

Identifies the maximum selected value.

+		Immutable
max(arg1: pg_lsn) → pg_lsn

Identifies the maximum selected value.

+		Immutable
max(arg1: timetz) → timetz

Identifies the maximum selected value.

+		Immutable
max(arg1: varbit) → varbit

Identifies the maximum selected value.

+		Immutable
min(arg1: bool) → bool

Identifies the minimum selected value.

+		Immutable
min(arg1: bytes) → bytes

Identifies the minimum selected value.

+		Immutable
min(arg1: date) → date

Identifies the minimum selected value.

+		Immutable
min(arg1: decimal) → decimal

Identifies the minimum selected value.

+		Immutable
min(arg1: float) → float

Identifies the minimum selected value.

+		Immutable
min(arg1: inet) → inet

Identifies the minimum selected value.

+		Immutable
min(arg1: int) → int

Identifies the minimum selected value.

+		Immutable
min(arg1: interval) → interval

Identifies the minimum selected value.

+		Immutable
min(arg1: string) → string

Identifies the minimum selected value.

+		Immutable
min(arg1: time) → time

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamp) → timestamp

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamptz) → timestamptz

Identifies the minimum selected value.

+		Immutable
min(arg1: uuid) → uuid

Identifies the minimum selected value.

+		Immutable
min(arg1: anyenum) → anyenum

Identifies the minimum selected value.

+		Immutable
min(arg1: box2d) → box2d

Identifies the minimum selected value.

+		Immutable
min(arg1: collatedstring{*}) → collatedstring{*}

Identifies the minimum selected value.

+		Immutable
min(arg1: geography) → geography

Identifies the minimum selected value.

+		Immutable
min(arg1: geometry) → geometry

Identifies the minimum selected value.

+		Immutable
min(arg1: jsonb) → jsonb

Identifies the minimum selected value.

+		Immutable
min(arg1: oid) → oid

Identifies the minimum selected value.

+		Immutable
min(arg1: pg_lsn) → pg_lsn

Identifies the minimum selected value.

+		Immutable
min(arg1: timetz) → timetz

Identifies the minimum selected value.

+		Immutable
min(arg1: varbit) → varbit

Identifies the minimum selected value.

+		Immutable
percentile_cont(arg1: float) → float

Continuous percentile: returns a float corresponding to the specified fraction in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float) → interval

Continuous percentile: returns an interval corresponding to the specified fraction in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_cont(arg1: float[]) → float[]

Continuous percentile: returns floats corresponding to the specified fractions in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float[]) → interval[]

Continuous percentile: returns intervals corresponding to the specified fractions in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_disc(arg1: float) → anyelement

Discrete percentile: returns the first input value whose position in the ordering equals or exceeds the specified fraction.

+		Immutable
percentile_disc(arg1: float[]) → anyelement

Discrete percentile: returns input values whose position in the ordering equals or exceeds the specified fractions.

+		Immutable
regr_avgx(arg1: decimal, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_count(arg1: decimal, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_intercept(arg1: decimal, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_r2(arg1: decimal, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_slope(arg1: decimal, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_sxx(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
sqrdiff(arg1: decimal) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: float) → float

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: int) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
st_collect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_extent(arg1: geometry) → box2d

Forms a Box2D that encapsulates all provided geometries.

+		Immutable
st_makeline(arg1: geometry) → geometry

Forms a LineString from Point, MultiPoint or LineStrings. Other shapes will be ignored.

+		Immutable
st_memcollect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_memunion(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
st_union(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
stddev(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: decimal) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: float) → float

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: int) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
string_agg(arg1: bytes, arg2: bytes) → bytes

Concatenates all selected values using the provided delimiter.

+		Immutable
string_agg(arg1: string, arg2: string) → string

Concatenates all selected values using the provided delimiter.

+		Immutable
sum(arg1: decimal) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: float) → float

Calculates the sum of the selected values.

+		Immutable
sum(arg1: int) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: interval) → interval

Calculates the sum of the selected values.

+		Immutable
sum_int(arg1: int) → int

Calculates the sum of the selected values.

+		Immutable
var_pop(arg1: decimal) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: float) → float

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: int) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_samp(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
variance(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
xor_agg(arg1: bytes) → bytes

Calculates the bitwise XOR of the selected values.

+		Immutable
xor_agg(arg1: int) → int

Calculates the bitwise XOR of the selected values.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-24.2/sql/functions.md b/src/current/_includes/cockroach-generated/release-24.2/sql/functions.md new file mode 100644 index 00000000000..93e0c310821 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.2/sql/functions.md @@ -0,0 +1,3523 @@ +### Array functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_append(array: bool[], elem: bool) → bool[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: bytes[], elem: bytes) → bytes[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: date[], elem: date) → date[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: decimal[], elem: decimal) → decimal[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: float[], elem: float) → float[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: inet[], elem: inet) → inet[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: int[], elem: int) → int[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: interval[], elem: interval) → interval[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: string[], elem: string) → string[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: time[], elem: time) → time[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamp[], elem: timestamp) → timestamp[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamptz[], elem: timestamptz) → timestamptz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: uuid[], elem: uuid) → uuid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: anyenum[], elem: anyenum) → anyenum[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: box2d[], elem: box2d) → box2d[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geography[], elem: geography) → geography[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geometry[], elem: geometry) → geometry[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: jsonb[], elem: jsonb) → jsonb[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: oid[], elem: oid) → oid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: refcursor[], elem: refcursor) → refcursor[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timetz[], elem: timetz) → timetz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: tuple[], elem: tuple) → tuple[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: varbit[], elem: varbit) → varbit[]

Appends elem to array, returning the result.

+		Immutable
array_cat(left: bool[], right: bool[]) → bool[]

Appends two arrays.

+		Immutable
array_cat(left: bytes[], right: bytes[]) → bytes[]

Appends two arrays.

+		Immutable
array_cat(left: date[], right: date[]) → date[]

Appends two arrays.

+		Immutable
array_cat(left: decimal[], right: decimal[]) → decimal[]

Appends two arrays.

+		Immutable
array_cat(left: float[], right: float[]) → float[]

Appends two arrays.

+		Immutable
array_cat(left: inet[], right: inet[]) → inet[]

Appends two arrays.

+		Immutable
array_cat(left: int[], right: int[]) → int[]

Appends two arrays.

+		Immutable
array_cat(left: interval[], right: interval[]) → interval[]

Appends two arrays.

+		Immutable
array_cat(left: string[], right: string[]) → string[]

Appends two arrays.

+		Immutable
array_cat(left: time[], right: time[]) → time[]

Appends two arrays.

+		Immutable
array_cat(left: timestamp[], right: timestamp[]) → timestamp[]

Appends two arrays.

+		Immutable
array_cat(left: timestamptz[], right: timestamptz[]) → timestamptz[]

Appends two arrays.

+		Immutable
array_cat(left: uuid[], right: uuid[]) → uuid[]

Appends two arrays.

+		Immutable
array_cat(left: anyenum[], right: anyenum[]) → anyenum[]

Appends two arrays.

+		Immutable
array_cat(left: box2d[], right: box2d[]) → box2d[]

Appends two arrays.

+		Immutable
array_cat(left: geography[], right: geography[]) → geography[]

Appends two arrays.

+		Immutable
array_cat(left: geometry[], right: geometry[]) → geometry[]

Appends two arrays.

+		Immutable
array_cat(left: jsonb[], right: jsonb[]) → jsonb[]

Appends two arrays.

+		Immutable
array_cat(left: oid[], right: oid[]) → oid[]

Appends two arrays.

+		Immutable
array_cat(left: pg_lsn[], right: pg_lsn[]) → pg_lsn[]

Appends two arrays.

+		Immutable
array_cat(left: refcursor[], right: refcursor[]) → refcursor[]

Appends two arrays.

+		Immutable
array_cat(left: timetz[], right: timetz[]) → timetz[]

Appends two arrays.

+		Immutable
array_cat(left: tuple[], right: tuple[]) → tuple[]

Appends two arrays.

+		Immutable
array_cat(left: varbit[], right: varbit[]) → varbit[]

Appends two arrays.

+		Immutable
array_length(input: anyelement[], array_dimension: int) → int

Calculates the length of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_lower(input: anyelement[], array_dimension: int) → int

Calculates the minimum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_position(array: bool[], elem: bool) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bool[], elem: bool, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: bytes[], elem: bytes) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bytes[], elem: bytes, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: date[], elem: date) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: date[], elem: date, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: decimal[], elem: decimal) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: decimal[], elem: decimal, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: float[], elem: float) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: float[], elem: float, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: inet[], elem: inet) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: inet[], elem: inet, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: int[], elem: int) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: int[], elem: int, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: interval[], elem: interval) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: interval[], elem: interval, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: string[], elem: string) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: string[], elem: string, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: time[], elem: time) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: time[], elem: time, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timestamp[], elem: timestamp) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamp[], elem: timestamp, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: uuid[], elem: uuid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: uuid[], elem: uuid, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: anyenum[], elem: anyenum) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: anyenum[], elem: anyenum, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: box2d[], elem: box2d) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: box2d[], elem: box2d, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: geography[], elem: geography) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geography[], elem: geography, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: geometry[], elem: geometry) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geometry[], elem: geometry, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: jsonb[], elem: jsonb) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: jsonb[], elem: jsonb, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: oid[], elem: oid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: oid[], elem: oid, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: refcursor[], elem: refcursor) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: refcursor[], elem: refcursor, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timetz[], elem: timetz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timetz[], elem: timetz, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: tuple[], elem: tuple) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: tuple[], elem: tuple, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: varbit[], elem: varbit) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: varbit[], elem: varbit, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_positions(array: bool[], elem: bool) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: bytes[], elem: bytes) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: date[], elem: date) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: decimal[], elem: decimal) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: float[], elem: float) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: inet[], elem: inet) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: int[], elem: int) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: interval[], elem: interval) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: string[], elem: string) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: time[], elem: time) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamp[], elem: timestamp) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamptz[], elem: timestamptz) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: uuid[], elem: uuid) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: anyenum[], elem: anyenum) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: box2d[], elem: box2d) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geography[], elem: geography) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geometry[], elem: geometry) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: jsonb[], elem: jsonb) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: oid[], elem: oid) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: pg_lsn[], elem: pg_lsn) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: refcursor[], elem: refcursor) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timetz[], elem: timetz) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: tuple[], elem: tuple) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: varbit[], elem: varbit) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_prepend(elem: bool, array: bool[]) → bool[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: bytes, array: bytes[]) → bytes[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: date, array: date[]) → date[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: decimal, array: decimal[]) → decimal[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: float, array: float[]) → float[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: inet, array: inet[]) → inet[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: int, array: int[]) → int[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: interval, array: interval[]) → interval[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: string, array: string[]) → string[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: time, array: time[]) → time[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamp, array: timestamp[]) → timestamp[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamptz, array: timestamptz[]) → timestamptz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: uuid, array: uuid[]) → uuid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: anyenum, array: anyenum[]) → anyenum[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: box2d, array: box2d[]) → box2d[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geography, array: geography[]) → geography[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geometry, array: geometry[]) → geometry[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: jsonb, array: jsonb[]) → jsonb[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: oid, array: oid[]) → oid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: pg_lsn, array: pg_lsn[]) → pg_lsn[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: refcursor, array: refcursor[]) → refcursor[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timetz, array: timetz[]) → timetz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: tuple, array: tuple[]) → tuple[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: varbit, array: varbit[]) → varbit[]

Prepends elem to array, returning the result.

+		Immutable
array_remove(array: bool[], elem: bool) → bool[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: bytes[], elem: bytes) → bytes[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: date[], elem: date) → date[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: decimal[], elem: decimal) → decimal[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: float[], elem: float) → float[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: inet[], elem: inet) → inet[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: int[], elem: int) → int[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: interval[], elem: interval) → interval[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: string[], elem: string) → string[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: time[], elem: time) → time[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamp[], elem: timestamp) → timestamp[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamptz[], elem: timestamptz) → timestamptz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: uuid[], elem: uuid) → uuid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: anyenum[], elem: anyenum) → anyenum[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: box2d[], elem: box2d) → box2d[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geography[], elem: geography) → geography[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geometry[], elem: geometry) → geometry[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: jsonb[], elem: jsonb) → jsonb[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: oid[], elem: oid) → oid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: refcursor[], elem: refcursor) → refcursor[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timetz[], elem: timetz) → timetz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: tuple[], elem: tuple) → tuple[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: varbit[], elem: varbit) → varbit[]

Remove from array all elements equal to elem.

+		Immutable
array_replace(array: bool[], toreplace: bool, replacewith: bool) → bool[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: bytes[], toreplace: bytes, replacewith: bytes) → bytes[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: date[], toreplace: date, replacewith: date) → date[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: decimal[], toreplace: decimal, replacewith: decimal) → decimal[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: float[], toreplace: float, replacewith: float) → float[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: inet[], toreplace: inet, replacewith: inet) → inet[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: int[], toreplace: int, replacewith: int) → int[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: interval[], toreplace: interval, replacewith: interval) → interval[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: string[], toreplace: string, replacewith: string) → string[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: time[], toreplace: time, replacewith: time) → time[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamp[], toreplace: timestamp, replacewith: timestamp) → timestamp[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamptz[], toreplace: timestamptz, replacewith: timestamptz) → timestamptz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: uuid[], toreplace: uuid, replacewith: uuid) → uuid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: anyenum[], toreplace: anyenum, replacewith: anyenum) → anyenum[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: box2d[], toreplace: box2d, replacewith: box2d) → box2d[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geography[], toreplace: geography, replacewith: geography) → geography[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geometry[], toreplace: geometry, replacewith: geometry) → geometry[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: jsonb[], toreplace: jsonb, replacewith: jsonb) → jsonb[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: oid[], toreplace: oid, replacewith: oid) → oid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: pg_lsn[], toreplace: pg_lsn, replacewith: pg_lsn) → pg_lsn[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: refcursor[], toreplace: refcursor, replacewith: refcursor) → refcursor[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timetz[], toreplace: timetz, replacewith: timetz) → timetz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: tuple[], toreplace: tuple, replacewith: tuple) → tuple[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: varbit[], toreplace: varbit, replacewith: varbit) → varbit[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_to_string(input: anyelement[], delim: string) → string

Join an array into a string with a delimiter.

+		Stable
array_to_string(input: anyelement[], delimiter: string, null: string) → string

Join an array into a string with a delimiter, replacing NULLs with a null string.

+		Stable
array_upper(input: anyelement[], array_dimension: int) → int

Calculates the maximum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
cardinality(input: anyelement[]) → int

Calculates the number of elements contained in input

+		Immutable
jsonb_array_to_string_array(input: jsonb) → string[]

Convert a JSONB array into a string array.

+		Immutable
string_to_array(str: string, delimiter: string) → string[]

Split a string into components on a delimiter.

+		Immutable
string_to_array(str: string, delimiter: string, null: string) → string[]

Split a string into components on a delimiter with a specified string to consider NULL.

+		Immutable
+ +### BOOL functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Matches case insensetively unescaped with pattern using escape as an escape token.

+		Immutable
inet_contained_by_or_equals(val: inet, container: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_contains_or_equals(container: inet, val: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_same_family(val: inet, val: inet) → bool

Checks if two IP addresses are of the same IP family.

+		Immutable
like_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
not_ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches case insensetively with pattern using escape as an escape token.

+		Immutable
not_like_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
not_similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
+ +### Comparison functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
greatest(anyelement...) → anyelement

Returns the element with the greatest value.

+		Immutable
least(anyelement...) → anyelement

Returns the element with the lowest value.

+		Immutable
num_nonnulls(anyelement...) → int

Returns the number of nonnull arguments.

+		Immutable
num_nulls(anyelement...) → int

Returns the number of null arguments.

+		Immutable
+ +### Cryptographic functions + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crypt(password: string, salt: string) → string

Generates a hash based on a password and salt. The hash algorithm and number of rounds if applicable are encoded in the salt.

+		Immutable
decrypt(data: bytes, key: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
decrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
digest(data: bytes, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
digest(data: string, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
encrypt(data: bytes, key: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
encrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
gen_random_bytes(count: int) → bytes

Returns count cryptographically strong random bytes. At most 1024 bytes can be extracted at a time.

+		Volatile
gen_salt(type: string) → string

Generates a salt for input into the crypt function using the default number of rounds.

+		Volatile
gen_salt(type: string, iter_count: int) → string

Generates a salt for input into the crypt function using iter_count number of rounds.

+		Volatile
hmac(data: bytes, key: bytes, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
hmac(data: string, key: string, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
+ +### DECIMAL functions + + + + + +
Function → ReturnsDescriptionVolatility
hlc_to_timestamp(hlc: decimal) → timestamptz

Returns a TimestampTZ representation of a CockroachDB HLC in decimal form.

+

Note that a TimestampTZ has less precision than a CockroachDB HLC. It is intended as +a convenience function to display HLCs in a print-friendly form. Use the decimal +value if you rely on the HLC for accuracy.

+		Immutable
+ +### Date and time functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
age(end: timestamptz, begin: timestamptz) → interval

Calculates the interval between begin and end, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use the timestamptz subtraction operator.

+		Immutable
age(val: timestamptz) → interval

Calculates the interval between val and the current time, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use now() - timestamptz.

+		Stable
clock_timestamp() → timestamp

Returns the current system time on one of the cluster nodes.

+		Volatile
clock_timestamp() → timestamptz

Returns the current system time on one of the cluster nodes.

+		Volatile
current_date() → date

Returns the date of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_timestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
date_part(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
date_part(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
date_trunc(element: string, input: date) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: interval) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: time) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero.

+

Compatible elements: hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamp) → timestamp

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamptz) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: timestamptz, timezone: string) → timestamptz

Truncates input to precision element in the specified timezone. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
experimental_follower_read_timestamp() → timestamptz

Same as follower_read_timestamp. This name is deprecated.

+		Volatile
experimental_strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
extract(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
extract(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
extract_duration(element: string, input: interval) → int

Extracts element from input. +Compatible elements: hour, minute, second, millisecond, microsecond. +This is deprecated in favor of extract which supports duration.

+		Immutable
follower_read_timestamp() → timestamptz

Returns a timestamp which is very likely to be safe to perform +against a follower replica.

+

This function is intended to be used with an AS OF SYSTEM TIME clause to perform +historical reads against a time which is recent but sufficiently old for reads +to be performed against the closest replica as opposed to the currently +leaseholder for a given range.

+

Note that this function requires an enterprise license on a CCL distribution to +return a result that is less likely the closest replica. It is otherwise +hardcoded as -4.8s from the statement time, which may not result in reading from the +nearest replica.

+		Volatile
localtimestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
make_date(year: int, month: int, day: int) → date

Create date (formatted according to ISO 8601) from year, month, and day fields (negative years signify BC).

+		Immutable
make_timestamp(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamp

Create timestamp (formatted according to ISO 8601) from year, month, day, hour, minute, and seconds fields (negative years signify BC).

+		Immutable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float, timezone: string) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
now() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
overlaps(s1: date, e1: date, s1: date, e2: date) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: date, e1: interval, s1: date, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: interval, s1: time, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: time, s1: time, e2: time) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: interval, s1: timestamp, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: timestamp, s1: timestamp, e2: timestamp) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamptz, e1: interval, s1: timestamptz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Stable
overlaps(s1: timestamptz, e1: timestamptz, s1: timestamptz, e2: timestamptz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: interval, s1: timetz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: timetz, s1: timetz, e2: timetz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
statement_timestamp() → timestamp

Returns the start time of the current statement.

+		Stable
statement_timestamp() → timestamptz

Returns the start time of the current statement.

+		Stable
strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
timeofday() → string

Returns the current system time on one of the cluster nodes as a string.

+		Stable
timezone(timezone: string, time: time) → timetz

Treat given time without time zone as located in the specified time zone.

+		Stable
timezone(timezone: string, timestamp: timestamp) → timestamptz

Treat given time stamp without time zone as located in the specified time zone.

+		Immutable
timezone(timezone: string, timestamptz: timestamptz) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Immutable
timezone(timezone: string, timestamptz_string: string) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Stable
timezone(timezone: string, timetz: timetz) → timetz

Convert given time with time zone to the new time zone.

+		Stable
to_char(date: date) → string

Convert an date to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(date: date, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_char(interval: interval) → string

Convert an interval to a string assuming the Postgres IntervalStyle.

+		Immutable
to_char(interval: interval, format: string) → string

Convert an interval to a string using the given format.

+		Stable
to_char(timestamp: timestamp) → string

Convert an timestamp to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(timestamp: timestamp, format: string) → string

Convert an timestamp to a string using the given format.

+		Stable
to_char(timestamptz: timestamptz, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_timestamp(timestamp: float) → timestamptz

Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to timestamp with time zone.

+		Immutable
transaction_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
with_max_staleness(max_staleness: interval) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_max_staleness(max_staleness: interval, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
+ +### Enum functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
enum_first(val: anyenum) → anyenum

Returns the first value of the input enum type.

+		Stable
enum_last(val: anyenum) → anyenum

Returns the last value of the input enum type.

+		Stable
enum_range(lower: anyenum, upper: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array between the two arguments (inclusive).

+		Stable
enum_range(val: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array.

+		Stable
+ +### FLOAT functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abs(val: decimal) → decimal

Calculates the absolute value of val.

+		Immutable
abs(val: float) → float

Calculates the absolute value of val.

+		Immutable
abs(val: int) → int

Calculates the absolute value of val.

+		Immutable
acos(val: float) → float

Calculates the inverse cosine of val.

+		Immutable
acosd(val: float) → float

Calculates the inverse cosine of val with the result in degrees

+		Immutable
acosh(val: float) → float

Calculates the inverse hyperbolic cosine of val.

+		Immutable
asin(val: float) → float

Calculates the inverse sine of val.

+		Immutable
asind(val: float) → float

Calculates the inverse sine of val with the result in degrees.

+		Immutable
asinh(val: float) → float

Calculates the inverse hyperbolic sine of val.

+		Immutable
atan(val: float) → float

Calculates the inverse tangent of val.

+		Immutable
atan2(x: float, y: float) → float

Calculates the inverse tangent of x/y.

+		Immutable
atan2d(x: float, y: float) → float

Calculates the inverse tangent of x/y with the result in degrees

+		Immutable
atand(val: float) → float

Calculates the inverse tangent of val with the result in degrees.

+		Immutable
atanh(val: float) → float

Calculates the inverse hyperbolic tangent of val.

+		Immutable
cbrt(val: decimal) → decimal

Calculates the cube root (∛) of val.

+		Immutable
cbrt(val: float) → float

Calculates the cube root (∛) of val.

+		Immutable
ceil(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
cos(val: float) → float

Calculates the cosine of val.

+		Immutable
cosd(val: float) → float

Calculates the cosine of val where val is in degrees.

+		Immutable
cosh(val: float) → float

Calculates the hyperbolic cosine of val.

+		Immutable
cot(val: float) → float

Calculates the cotangent of val.

+		Immutable
cotd(val: float) → float

Calculates the cotangent of val where val is in degrees.

+		Immutable
degrees(val: float) → float

Converts val as a radian value to a degree value.

+		Immutable
div(x: decimal, y: decimal) → decimal

Calculates the integer quotient of x/y.

+		Immutable
div(x: float, y: float) → float

Calculates the integer quotient of x/y.

+		Immutable
div(x: int, y: int) → int

Calculates the integer quotient of x/y.

+		Immutable
exp(val: decimal) → decimal

Calculates e ^ val.

+		Immutable
exp(val: float) → float

Calculates e ^ val.

+		Immutable
floor(val: decimal) → decimal

Calculates the largest integer not greater than val.

+		Immutable
floor(val: float) → float

Calculates the largest integer not greater than val.

+		Immutable
floor(val: int) → float

Calculates the largest integer not greater than val.

+		Immutable
isnan(val: decimal) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
isnan(val: float) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
ln(val: decimal) → decimal

Calculates the natural log of val.

+		Immutable
ln(val: float) → float

Calculates the natural log of val.

+		Immutable
log(b: decimal, x: decimal) → decimal

Calculates the base b log of val.

+		Immutable
log(b: float, x: float) → float

Calculates the base b log of val.

+		Immutable
log(val: decimal) → decimal

Calculates the base 10 log of val.

+		Immutable
log(val: float) → float

Calculates the base 10 log of val.

+		Immutable
mod(x: decimal, y: decimal) → decimal

Calculates x%y.

+		Immutable
mod(x: float, y: float) → float

Calculates x%y.

+		Immutable
mod(x: int, y: int) → int

Calculates x%y.

+		Immutable
pi() → float

Returns the value for pi (3.141592653589793).

+		Immutable
pow(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
pow(x: float, y: float) → float

Calculates x^y.

+		Immutable
pow(x: int, y: int) → int

Calculates x^y.

+		Immutable
power(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
power(x: float, y: float) → float

Calculates x^y.

+		Immutable
power(x: int, y: int) → int

Calculates x^y.

+		Immutable
radians(val: float) → float

Converts val as a degree value to a radians value.

+		Immutable
random() → float

Returns a random floating-point number between 0 (inclusive) and 1 (exclusive). Note that the value contains at most 53 bits of randomness.

+		Volatile
round(input: decimal, decimal_accuracy: int) → decimal

Keeps decimal_accuracy number of figures to the right of the zero position in input using half away from zero rounding. If decimal_accuracy is not in the range -2^31…(2^31-1), the results are undefined.

+		Immutable
round(input: float, decimal_accuracy: int) → float

Keeps decimal_accuracy number of figures to the right of the zero position in input using half to even (banker’s) rounding.

+		Immutable
round(val: decimal) → decimal

Rounds val to the nearest integer, half away from zero: round(+/-2.4) = +/-2, round(+/-2.5) = +/-3.

+		Immutable
round(val: float) → float

Rounds val to the nearest integer using half to even (banker’s) rounding.

+		Immutable
setseed(seed: float) → void

Sets the seed for subsequent random() calls in this session (value between -1.0 and 1.0, inclusive). There are no guarantees as to how this affects the seed of random() calls that appear in the same query as setseed().

+		Volatile
sign(val: decimal) → decimal

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: float) → float

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: int) → int

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sin(val: float) → float

Calculates the sine of val.

+		Immutable
sind(val: float) → float

Calculates the sine of val where val is in degrees.

+		Immutable
sinh(val: float) → float

Calculates the hyperbolic sine of val.

+		Immutable
sqrt(val: decimal) → decimal

Calculates the square root of val.

+		Immutable
sqrt(val: float) → float

Calculates the square root of val.

+		Immutable
tan(val: float) → float

Calculates the tangent of val.

+		Immutable
tand(val: float) → float

Calculates the tangent of val where val is in degrees.

+		Immutable
tanh(val: float) → float

Calculates the hyperbolic tangent of val.

+		Immutable
trunc(val: decimal) → decimal

Truncates the decimal values of val.

+		Immutable
trunc(val: decimal, scale: int) → decimal

Truncate val to scale decimal places

+		Immutable
trunc(val: float) → float

Truncates the decimal values of val.

+		Immutable
+ +### Full Text Search functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
phraseto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The <-> operator is inserted between each token in the input.

+		Immutable
phraseto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The <-> operator is inserted between each token in the input.

+		Stable
plainto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The & operator is inserted between each token in the input.

+		Immutable
plainto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The & operator is inserted between each token in the input.

+		Stable
to_tsquery(config: string, text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the specified configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Immutable
to_tsquery(text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the default configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Stable
to_tsvector(config: string, text: string) → tsvector

Converts text to a tsvector, normalizing words according to the specified configuration. Position information is included in the result.

+		Immutable
to_tsvector(text: string) → tsvector

Converts text to a tsvector, normalizing words according to the default configuration. Position information is included in the result.

+		Stable
ts_parse(parser_name: string, document: string) → tuple{int AS tokid, string AS token}

ts_parse parses the given document and returns a series of records, one for each token produced by parsing. Each record includes a tokid showing the assigned token type and a token which is the text of the token.

+		Stable
ts_rank(vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
+ +### Fuzzy String Matching functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
levenshtein(source: string, target: string) → int

Calculates the Levenshtein distance between two strings. Maximum input length is 255 characters.

+		Immutable
levenshtein(source: string, target: string, ins_cost: int, del_cost: int, sub_cost: int) → int

Calculates the Levenshtein distance between two strings. The cost parameters specify how much to charge for each edit operation. Maximum input length is 255 characters.

+		Immutable
metaphone(source: string, max_output_length: int) → string

Convert a string to its Metaphone code. Maximum input length is 255 characters

+		Immutable
soundex(source: string) → string

Convert a string to its Soundex code.

+		Immutable
+ +### ID generation functions + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
experimental_uuid_v4() → bytes

Returns a UUID.

+		Volatile
gen_random_ulid() → uuid

Generates a random ULID and returns it as a value of UUID type.

+		Volatile
gen_random_uuid() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
unique_rowid() → int

Returns a unique ID used by CockroachDB to generate unique row IDs if a Primary Key isn’t defined for the table. The value is a combination of the insert timestamp and the ID of the node executing the statement, which guarantees this combination is globally unique. However, there can be gaps and the order is not completely guaranteed.

+		Volatile
unordered_unique_rowid() → int

Returns a unique ID. The value is a combination of the insert timestamp (bit-reversed) and the ID of the node executing the statement, which guarantees this combination is globally unique. The way it is generated is statistically likely to not have any ordering relative to previously generated values.

+		Volatile
uuid_generate_v1() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. To avoid exposing the server’s real MAC address, this uses a random MAC address and a timestamp. Essentially, this is an alias for uuid_generate_v1mc.

+		Volatile
uuid_generate_v1mc() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. This uses a random MAC address and a timestamp.

+		Volatile
uuid_generate_v3(namespace: uuid, name: string) → uuid

Generates a version 3 UUID in the given namespace using the specified input name, with md5 as the hashing method. The namespace should be one of the special constants produced by the uuid_ns_*() functions.

+		Immutable
uuid_generate_v4() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
uuid_generate_v5(namespace: uuid, name: string) → uuid

Generates a version 5 UUID in the given namespace using the specified input name. This is similar to a version 3 UUID, except it uses SHA-1 for hashing.

+		Immutable
uuid_nil() → uuid

Returns a nil UUID constant.

+		Immutable
uuid_ns_dns() → uuid

Returns a constant designating the DNS namespace for UUIDs.

+		Immutable
uuid_ns_oid() → uuid

Returns a constant designating the ISO object identifier (OID) namespace for UUIDs. These are unrelated to the OID type used internally in the database.

+		Immutable
uuid_ns_url() → uuid

Returns a constant designating the URL namespace for UUIDs.

+		Immutable
uuid_ns_x500() → uuid

Returns a constant designating the X.500 distinguished name (DN) namespace for UUIDs.

+		Immutable
uuid_v4() → bytes

Returns a UUID.

+		Volatile
+ +### INET functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abbrev(val: inet) → string

Converts the combined IP address and prefix length to an abbreviated display format as text.For INET types, this will omit the prefix length if it’s not the default (32 or IPv4, 128 for IPv6)

+

For example, abbrev('192.168.1.2/24') returns '192.168.1.2/24'

+		Immutable
broadcast(val: inet) → inet

Gets the broadcast address for the network address represented by the value.

+

For example, broadcast('192.168.1.2/24') returns '192.168.1.255/24'

+		Immutable
family(val: inet) → int

Extracts the IP family of the value; 4 for IPv4, 6 for IPv6.

+

For example, family('::1') returns 6

+		Immutable
host(val: inet) → string

Extracts the address part of the combined address/prefixlen value as text.

+

For example, host('192.168.1.2/16') returns '192.168.1.2'

+		Immutable
hostmask(val: inet) → inet

Creates an IP host mask corresponding to the prefix length in the value.

+

For example, hostmask('192.168.1.2/16') returns '0.0.255.255'

+		Immutable
masklen(val: inet) → int

Retrieves the prefix length stored in the value.

+

For example, masklen('192.168.1.2/16') returns 16

+		Immutable
netmask(val: inet) → inet

Creates an IP network mask corresponding to the prefix length in the value.

+

For example, netmask('192.168.1.2/16') returns '255.255.0.0'

+		Immutable
set_masklen(val: inet, prefixlen: int) → inet

Sets the prefix length of val to prefixlen.

+

For example, set_masklen('192.168.1.2', 16) returns '192.168.1.2/16'.

+		Immutable
+ +### INT functions + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crc32c(bytes...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32c(string...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32ieee(bytes...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
crc32ieee(string...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
fnv32(bytes...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32(string...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32a(bytes...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv32a(string...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64(bytes...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64(string...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64a(bytes...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64a(string...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
width_bucket(operand: decimal, b1: decimal, b2: decimal, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2.

+		Immutable
width_bucket(operand: int, b1: int, b2: int, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2.

+		Immutable
width_bucket(operand: anyelement, thresholds: anyelement[]) → int

return the bucket number to which operand would be assigned given an array listing the lower bounds of the buckets; returns 0 for an input less than the first lower bound; the thresholds array must be sorted, smallest first, or unexpected results will be obtained

+		Immutable
+ +### JSONB functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_to_json(array: anyelement[]) → jsonb

Returns the array as JSON or JSONB.

+		Stable
array_to_json(array: anyelement[], pretty_bool: bool) → jsonb

Returns the array as JSON or JSONB.

+		Stable
json_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
json_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
json_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
json_build_array(anyelement...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
json_build_object(anyelement...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
json_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
json_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
json_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
json_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
json_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
json_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
json_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
json_remove_path(val: jsonb, path: string[]) → jsonb

Remove the specified path from the JSON object.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
json_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
json_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
json_valid(string: string) → bool

Returns whether the given string is a valid JSON or not

+		Immutable
jsonb_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
jsonb_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
jsonb_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
jsonb_build_array(anyelement...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
jsonb_build_object(anyelement...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
jsonb_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
jsonb_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
jsonb_exists_any(json: jsonb, array: string[]) → bool

Returns whether any of the strings in the text array exist as top-level keys or array elements

+		Immutable
jsonb_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments. new_val will be inserted before path target.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb, insert_after: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If insert_after is true (default is false), new_val will be inserted after path target.

+		Immutable
jsonb_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
jsonb_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
jsonb_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
jsonb_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
jsonb_pretty(val: jsonb) → string

Returns the given JSON value as a STRING indented and with newlines.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
jsonb_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
jsonb_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
row_to_json(row: tuple) → jsonb

Returns the row as a JSON object.

+		Stable
to_json(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
to_jsonb(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
+ +### Multi-region functions + + + + + + + +
Function → ReturnsDescriptionVolatility
default_to_database_primary_region(val: string) → string

Returns the given region if the region has been added to the current database. +Otherwise, this will return the primary region of the current database. +This will error if the current database is not a multi-region database.

+		Stable
gateway_region() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
rehome_row() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
+ +### PGVector functions + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cosine_distance(v1: vector, v2: vector) → float

Returns the cosine distance between the two vectors.

+		Immutable
inner_product(v1: vector, v2: vector) → float

Returns the inner product between the two vectors.

+		Immutable
l1_distance(v1: vector, v2: vector) → float

Returns the Manhattan distance between the two vectors.

+		Immutable
l2_distance(v1: vector, v2: vector) → float

Returns the Euclidean distance between the two vectors.

+		Immutable
vector_dims(vector: vector) → int

Returns the number of the dimensions in the vector.

+		Immutable
vector_norm(vector: vector) → float

Returns the Euclidean norm of the vector.

+		Immutable
+ +### STRING[] functions + + + + + + +
Function → ReturnsDescriptionVolatility
regexp_split_to_array(string: string, pattern: string) → string[]

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_array(string: string, pattern: string, flags: string) → string[]

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
+ +### Sequence functions + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
currval(sequence_name: string) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
currval(sequence_name: regclass) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
lastval() → int

Return value most recently obtained with nextval in this session.

+		Volatile
nextval(sequence_name: string) → int

Advances the given sequence and returns its new value.

+		Volatile
nextval(sequence_name: regclass) → int

Advances the given sequence and returns its new value.

+		Volatile
setval(sequence_name: string, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: string, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
setval(sequence_name: regclass, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: regclass, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
+ +### Set-returning functions + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
aclexplode(aclitems: string[]) → tuple{oid AS grantor, oid AS grantee, string AS privilege_type, bool AS is_grantable}

Produces a virtual table containing aclitem stuff (returns no rows as this feature is unsupported in CockroachDB)

+		Stable
generate_series(start: int, end: int) → int

Produces a virtual table containing the integer values from start to end, inclusive.

+		Immutable
generate_series(start: int, end: int, step: int) → int

Produces a virtual table containing the integer values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamp, end: timestamp, step: interval) → timestamp

Produces a virtual table containing the timestamp values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamptz, end: timestamptz, step: interval) → timestamptz

Produces a virtual table containing the timestampTZ values from start to end, inclusive, by increment of step.

+		Immutable
generate_subscripts(array: anyelement[]) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int, reverse: bool) → int

Returns a series comprising the given array’s subscripts.

+

When reverse is true, the series is returned in reverse order.

+		Immutable
information_schema._pg_expandarray(input: anyelement[]) → tuple{anyelement AS x, int AS n}

Returns the input array as a set of rows with an index

+		Immutable
json_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
json_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
json_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
jsonb_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
jsonb_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
jsonb_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
pg_get_keywords() → tuple{string AS word, string AS catcode, string AS catdesc}

Produces a virtual table containing the keywords known to the SQL parser.

+		Immutable
pg_options_to_table(options: string[]) → tuple{string AS option_name, string AS option_value}

Converts the options array format to a table.

+		Stable
regexp_split_to_table(string: string, pattern: string) → string

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_table(string: string, pattern: string, flags: string) → string

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
unnest(anyelement[], anyelement[], anyelement[]...) → tuple{anyelement AS unnest, anyelement AS unnest, anyelement AS unnest}

Returns the input arrays as a set of rows

+		Immutable
unnest(input: anyelement[]) → anyelement

Returns the input array as a set of rows

+		Immutable
workload_index_recs() → string

Returns set of index recommendations

+		Immutable
workload_index_recs(timestamptz: timestamptz) → string

Returns set of index recommendations

+		Immutable
+ +### Spatial functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
_st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
geometrytype(geometry: geometry) → string

Returns the type of geometry as a string.

+

This function utilizes the GEOS module.

+		Immutable
geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
postgis_addbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_dropbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_extensions_upgrade() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_full_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_geos_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_getbbox(geometry: geometry) → box2d

Returns a box2d encapsulating the given Geometry.

+		Immutable
postgis_hasbbox(geometry: geometry) → bool

Returns whether a given Geometry has a bounding box. False for points and empty geometries; always true otherwise.

+		Immutable
postgis_lib_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_lib_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_liblwgeom_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_libxml_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_proj_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_installed() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_released() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_wagyu_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
st_addmeasure(geometry: geometry, start: float, end: float) → geometry

Returns a copy of a LineString or MultiLineString with measure coordinates linearly interpolated between the specified start and end values. Any existing M coordinates will be overwritten.

+		Immutable
st_addpoint(line_string: geometry, point: geometry) → geometry

Adds a Point to the end of a LineString.

+		Immutable
st_addpoint(line_string: geometry, point: geometry, index: int) → geometry

Adds a Point to a LineString at the given 0-based index (-1 to append).

+		Immutable
st_affine(geometry: geometry, a: float, b: float, c: float, d: float, e: float, f: float, g: float, h: float, i: float, x_off: float, y_off: float, z_off: float) → geometry

Applies a 3D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b c x_off \ / x
+| d e f y_off | | y | +| g h i z_off | | z | +\ 0 0 0 1 / \ 0 /

+		Immutable
st_affine(geometry: geometry, a: float, b: float, d: float, e: float, x_off: float, y_off: float) → geometry

Applies a 2D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b x_off \ / x
+| d e y_off | | y | +\ 0 0 1 / \ 0 /

+		Immutable
st_angle(line1: geometry, line2: geometry) → float

Returns the clockwise angle between two LINESTRING geometries, treating them as vectors between their start- and endpoints. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry) → float

Returns the clockwise angle between the vectors formed by point2,point1 and point2,point3. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry, point4: geometry) → float

Returns the clockwise angle between the vectors formed by point1,point2 and point3,point4. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_area(geography: geography) → float

Returns the area of the given geography in meters^2. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geography: geography, use_spheroid: bool) → float

Returns the area of the given geography in meters^2.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_area(geometry_str: string) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_area2d(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_asbinary(geography: geography) → bytes

Returns the WKB representation of a given Geography.

+		Immutable
st_asbinary(geography: geography, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asbinary(geometry: geometry) → bytes

Returns the WKB representation of a given Geometry.

+		Immutable
st_asbinary(geometry: geometry, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asencodedpolyline(geometry: geometry) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Preserves 5 decimal places.

+		Immutable
st_asencodedpolyline(geometry: geometry, precision: int4) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+		Immutable
st_asewkb(geography: geography) → bytes

Returns the EWKB representation of a given Geography.

+		Immutable
st_asewkb(geometry: geometry) → bytes

Returns the EWKB representation of a given Geometry.

+		Immutable
st_asewkt(geography: geography) → string

Returns the EWKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_asewkt(geography: geography, max_decimal_digits: int) → string

Returns the EWKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry: geometry) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_asewkt(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry_str: string) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asewkt(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geography: geography) → string

Returns the GeoJSON representation of a given Geography. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option (default for Geography)
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326
    • +
+		Immutable
st_asgeojson(geometry: geometry) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+		Immutable
st_asgeojson(geometry_str: string) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(row: tuple) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(row: tuple, geo_column: string) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. Coordinates have a maximum of 9 decimal digits.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int, pretty: bool) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value. Output will be pretty printed in JSON if pretty is true.

+		Stable
st_ashexewkb(geography: geography) → string

Returns the EWKB representation in hex of a given Geography.

+		Immutable
st_ashexewkb(geography: geography, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexewkb(geometry: geometry) → string

Returns the EWKB representation in hex of a given Geometry.

+		Immutable
st_ashexewkb(geometry: geometry, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexwkb(geography: geography) → string

Returns the WKB representation in hex of a given Geography.

+		Immutable
st_ashexwkb(geometry: geometry) → string

Returns the WKB representation in hex of a given Geometry.

+		Immutable
st_askml(geography: geography) → string

Returns the KML representation of a given Geography.

+		Immutable
st_askml(geometry: geometry) → string

Returns the KML representation of a given Geometry.

+		Immutable
st_askml(geometry_str: string) → string

Returns the KML representation of a given Geometry.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping. +Uses 4096 as the tile extent size in tile coordinate space.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int, clip: bool) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds if required.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry can be transformed, and clipped if required.

+		Immutable
st_astext(geography: geography) → string

Returns the WKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_astext(geography: geography, max_decimal_digits: int) → string

Returns the WKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry: geometry) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_astext(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry_str: string) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astext(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int, precision_m: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_azimuth(geography_a: geography, geography_b: geography) → float

Returns the azimuth in radians of the segment defined by the given point geographies, or NULL if the two points are coincident. It is solved using the Inverse geodesic problem.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_azimuth(geometry_a: geometry, geometry_b: geometry) → float

Returns the azimuth in radians of the segment defined by the given point geometries, or NULL if the two points are coincident.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+		Immutable
st_bdpolyfromtext(str: string, srid: int) → geometry

Returns a Polygon from multilinestring WKT with a SRID. If the input is not a multilinestring an error will be thrown.

+		Immutable
st_boundary(geometry: geometry) → geometry

Returns the closure of the combinatorial boundary of this Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_box2dfromgeohash(geohash: string) → box2d

Return a Box2D from a GeoHash string with max precision.

+		Immutable
st_box2dfromgeohash(geohash: string, precision: int) → box2d

Return a Box2D from a GeoHash string with supplied precision.

+		Immutable
st_buffer(geography: geography, distance: float) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, buffer_style_params: string) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, quad_segs: int) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geometry: geometry, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry_str: string, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_centroid(geography: geography) → geography

Returns the centroid of given geography. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geography: geography, use_spheroid: bool) → geography

Returns the centroid of given geography.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geometry: geometry) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_centroid(geometry_str: string) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_clipbybox2d(geometry: geometry, box2d: box2d) → geometry

Clips the geometry to conform to the bounding box specified by box2d.

+		Immutable
st_closestpoint(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the 2-dimensional point on geometry_a that is closest to geometry_b. This is the first point of the shortest line.

+		Immutable
st_collectionextract(geometry: geometry, type: int) → geometry

Given a collection, returns a multitype consisting only of elements of the specified type. If there are no elements of the given type, an EMPTY geometry is returned. Types are specified as 1=POINT, 2=LINESTRING, 3=POLYGON - other types are not supported.

+		Immutable
st_collectionhomogenize(geometry: geometry) → geometry

Returns the “simplest” representation of a collection’s contents. Collections of a single type will be returned as an appopriate multitype, or a singleton if it only contains a single geometry.

+		Immutable
st_combinebbox(box2d: box2d, geometry: geometry) → box2d

Combines the current bounding box with the bounding box of the Geometry.

+		Immutable
st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_convexhull(geometry: geometry) → geometry

Returns a geometry that represents the Convex Hull of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_coorddim(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_difference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the difference of two Geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_dimension(geometry: geometry) → int

Returns the number of topological dimensions of a given Geometry.

+		Immutable
st_disjoint(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a does not overlap, touch or is within geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_distance(geography_a: geography, geography_b: geography) → float

Returns the distance in meters between geography_a and geography_b. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geography_a: geography, geography_b: geography, use_spheroid: bool) → float

Returns the distance in meters between geography_a and geography_b.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance between the given geometries.

+		Immutable
st_distance(geometry_a_str: string, geometry_b_str: string) → float

Returns the distance between the given geometries.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_distancesphere(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_distancespheroid(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a spheroid.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_endpoint(geometry: geometry) → geometry

Returns the last point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_envelope(box2d: box2d) → geometry

Returns a bounding geometry for the given box.

+		Immutable
st_envelope(geometry: geometry) → geometry

Returns a bounding envelope for the given geometry.

+

For geometries which have a POINT or LINESTRING bounding box (i.e. is a single point +or a horizontal or vertical line), a POINT or LINESTRING is returned. Otherwise, the +returned POLYGON will be ordered Bottom Left, Top Left, Top Right, Bottom Right, +Bottom Left.

+		Immutable
st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string, parent_only: bool) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+

The parent_only boolean is always ignored.

+		Stable
st_estimatedextent(table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_expand(box2d: box2d, delta: float) → box2d

Extends the box2d by delta units across all dimensions.

+		Immutable
st_expand(box2d: box2d, delta_x: float, delta_y: float) → box2d

Extends the box2d by delta_x units in the x dimension and delta_y units in the y dimension.

+		Immutable
st_expand(geometry: geometry, delta: float) → geometry

Extends the bounding box represented by the geometry by delta units across all dimensions, returning a Polygon representing the new bounding box.

+		Immutable
st_expand(geometry: geometry, delta_x: float, delta_y: float) → geometry

Extends the bounding box represented by the geometry by delta_x units in the x dimension and delta_y units in the y dimension, returning a Polygon representing the new bounding box.

+		Immutable
st_exteriorring(geometry: geometry) → geometry

Returns the exterior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon.

+		Immutable
st_flipcoordinates(geometry: geometry) → geometry

Returns a new geometry with the X and Y axes flipped.

+		Immutable
st_force2d(geometry: geometry) → geometry

Returns a Geometry that is forced into XY layout with any Z or M dimensions discarded.

+		Immutable
st_force3d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to 0. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry, defaultM: float) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to the specified default M value. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force4d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZM layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float, defaultM: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified Z value. If a M coordinate doesn’t exist, it will be set to the specified M value.

+		Immutable
st_forcecollection(geometry: geometry) → geometry

Converts the geometry into a GeometryCollection.

+		Immutable
st_forcepolygonccw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_forcepolygoncw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Frechet distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Frechet distance between the given geometries, with the given segment densification (range 0.0-1.0, -1 to disable).

+

Smaller densify_frac gives a more accurate Fréchet distance. However, the computation time and memory usage increases with the square of the number of subsegments.

+

This function utilizes the GEOS module.

+		Immutable
st_generatepoints(geometry: geometry, npoints: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. Uses system time as a seed. +The requested number of points must be not larger than 65336.

+		Volatile
st_generatepoints(geometry: geometry, npoints: int4, seed: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. +The requested number of points must be not larger than 65336.

+		Immutable
st_geogfromewkb(val: bytes) → geography

Returns the Geography from an EWKB representation.

+		Immutable
st_geogfromewkt(val: string) → geography

Returns the Geography from an EWKT representation.

+		Immutable
st_geogfromgeojson(val: string) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromgeojson(val: jsonb) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geogfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geogfromwkb(bytes: bytes, srid: int) → geography

Returns the Geography from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geogfromwkb(val: bytes) → geography

Returns the Geography from a WKB (or EWKB) representation.

+		Immutable
st_geographyfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geographyfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geohash(geography: geography) → string

Returns a GeoHash representation of the geeographywith full precision if a point is provided, or with variable precision based on the size of the feature.

+		Immutable
st_geohash(geography: geography, precision: int) → string

Returns a GeoHash representation of the geography with the supplied precision.

+		Immutable
st_geohash(geometry: geometry) → string

Returns a GeoHash representation of the geometry with full precision if a point is provided, or with variable precision based on the size of the feature. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geohash(geometry: geometry, precision: int) → string

Returns a GeoHash representation of the geometry with the supplied precision. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geomcollfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomcollfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geometryfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geometryfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geometryn(geometry: geometry, n: int) → geometry

Returns the n-th Geometry (1-indexed). Returns NULL if out of bounds.

+		Immutable
st_geometrytype(geometry: geometry) → string

Returns the type of geometry as a string prefixed with ST_.

+

This function utilizes the GEOS module.

+		Immutable
st_geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
st_geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
st_geomfromgeohash(geohash: string) → geometry

Return a POLYGON Geometry from a GeoHash string with max precision.

+		Immutable
st_geomfromgeohash(geohash: string, precision: int) → geometry

Return a POLYGON Geometry from a GeoHash string with supplied precision.

+		Immutable
st_geomfromgeojson(val: string) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromgeojson(val: jsonb) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geomfromwkb(bytes: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geomfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_hasarc(geometry: geometry) → bool

Returns whether there is a CIRCULARSTRING in the geometry.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Hausdorff distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Hausdorff distance between the given geometries, with the given segment densification (range 0.0-1.0).

+

This function utilizes the GEOS module.

+		Immutable
st_interiorringn(geometry: geometry, n: int) → geometry

Returns the n-th (1-indexed) interior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon, or the ring does not exist.

+		Immutable
st_intersection(geography_a: geography, geography_b: geography) → geography

Returns the point intersections of the given geographies.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a_str: string, geometry_b_str: string) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_isclosed(geometry: geometry) → bool

Returns whether the geometry is closed as defined by whether the start and end points are coincident. Points are considered closed, empty geometries are not. For collections and multi-types, all members must be closed, as must all polygon rings.

+		Immutable
st_iscollection(geometry: geometry) → bool

Returns whether the geometry is of a collection type (including multi-types).

+		Immutable
st_isempty(geometry: geometry) → bool

Returns whether the geometry is empty.

+		Immutable
st_ispolygonccw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are considered counter-clockwise.

+		Immutable
st_ispolygoncw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are considered clockwise.

+		Immutable
st_isring(geometry: geometry) → bool

Returns whether the geometry is a single linestring that is closed and simple, as defined by ST_IsClosed and ST_IsSimple.

+

This function utilizes the GEOS module.

+		Immutable
st_issimple(geometry: geometry) → bool

Returns true if the geometry has no anomalous geometric points, e.g. that it intersects with or lies tangent to itself.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry) → bool

Returns whether the geometry is valid as defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry, flags: int) → bool

Returns whether the geometry is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry) → string

Returns a string containing the reason the geometry is invalid along with the point of interest, or “Valid Geometry” if it is valid. Validity is defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry, flags: int) → string

Returns the reason the geometry is invalid or “Valid Geometry” if it is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidtrajectory(geometry: geometry) → bool

Returns whether the geometry encodes a valid trajectory.

+

Note the geometry must be a LineString with M coordinates.

+		Immutable
st_length(geography: geography) → float

Returns the length of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geography: geography, use_spheroid: bool) → float

Returns the length of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_length(geometry_str: string) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_length2d(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_linecrossingdirection(linestring_a: geometry, linestring_b: geometry) → int

Returns an interger value defining behavior of crossing of lines: +0: lines do not cross, +-1: linestring_b crosses linestring_a from right to left, +1: linestring_b crosses linestring_a from left to right, +-2: linestring_b crosses linestring_a multiple times from right to left, +2: linestring_b crosses linestring_a multiple times from left to right, +-3: linestring_b crosses linestring_a multiple times from left to left, +3: linestring_b crosses linestring_a multiple times from right to right.

+

Note that the top vertex of the segment touching another line does not count as a crossing, but the bottom vertex of segment touching another line is considered a crossing.

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string) → geometry

Creates a LineString from an Encoded Polyline string.

+

Returns valid results only if the polyline was encoded with 5 decimal places.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string, precision: int4) → geometry

Creates a LineString from an Encoded Polyline string.

+

Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefrommultipoint(geometry: geometry) → geometry

Creates a LineString from a MultiPoint geometry.

+		Immutable
st_linefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_lineinterpolatepoint(geometry: geometry, fraction: float) → geometry

Returns a point along the given LineString which is at given fraction of LineString’s total length.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float, repeat: bool) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length. If repeat is false (default true) then it returns first point.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_linelocatepoint(line: geometry, point: geometry) → float

Returns a float between 0 and 1 representing the location of the closest point on LineString to the given Point, as a fraction of total 2d line length.

+		Immutable
st_linemerge(geometry: geometry) → geometry

Returns a LineString or MultiLineString by joining together constituents of a MultiLineString with matching endpoints. If the input is not a MultiLineString or LineString, an empty GeometryCollection is returned.

+

This function utilizes the GEOS module.

+		Immutable
st_linestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: decimal, end_fraction: decimal) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: float, end_fraction: float) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_longestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the max distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the maximum distance between the geometry’s vertexes. The function will return the longest line that was discovered first when comparing maximum distances if more than one is found.

+		Immutable
st_m(geometry: geometry) → float

Returns the M coordinate of a geometry if it is a Point.

+		Immutable
st_makebox2d(geometry_a: geometry, geometry_b: geometry) → box2d

Creates a box2d from two points. Errors if arguments are not two non-empty points.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with SRID 0.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float, srid: int) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with the given SRID.

+		Immutable
st_makepoint(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float) → geometry

Returns a new Point with the given X, Y, and Z coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float, m: float) → geometry

Returns a new Point with the given X, Y, Z, and M coordinates.

+		Immutable
st_makepointm(x: float, y: float, m: float) → geometry

Returns a new Point with the given X, Y, and M coordinates.

+		Immutable
st_makepolygon(geometry: geometry) → geometry

Returns a new Polygon with the given outer LineString.

+		Immutable
st_makepolygon(outer: geometry, interior: anyelement[]) → geometry

Returns a new Polygon with the given outer LineString and interior (hole) LineString(s).

+		Immutable
st_makevalid(geometry: geometry) → geometry

Returns a valid form of the given geometry according to the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_maxdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the maximum distance across every pair of points comprising the given geometries. Note if the geometries are the same, it will return the maximum distance between the geometry’s vertexes.

+		Immutable
st_memsize(geometry: geometry) → int

Returns the amount of memory space (in bytes) the geometry takes.

+		Immutable
st_minimumboundingcircle(geometry: geometry) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingcircle(geometry: geometry, num_segs: int) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingradius(geometry: geometry) → tuple{geometry AS center, float AS radius}

Returns a record containing the center point and radius of the smallest circle that can fully contains the given geometry.

+		Immutable
st_minimumclearance(geometry: geometry) → float

Returns the minimum distance a vertex can move before producing an invalid geometry. Returns Infinity if no minimum clearance can be found (e.g. for a single point).

+		Immutable
st_minimumclearanceline(geometry: geometry) → geometry

Returns a LINESTRING spanning the minimum distance a vertex can move before producing an invalid geometry. If no minimum clearance can be found (e.g. for a single point), an empty LINESTRING is returned.

+		Immutable
st_mlinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mlinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mpointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multi(geometry: geometry) → geometry

Returns the geometry as a new multi-geometry, e.g converts a POINT to a MULTIPOINT. If the input is already a multitype or collection, it is returned as is.

+		Immutable
st_multilinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multipointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_ndims(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_node(geometry: geometry) → geometry

Adds a node on a geometry for each intersection. Resulting geometry is always a MultiLineString.

+		Immutable
st_normalize(geometry: geometry) → geometry

Returns the geometry in its normalized form.

+

This function utilizes the GEOS module.

+		Immutable
st_npoints(geometry: geometry) → int

Returns the number of points in a given Geometry. Works for any shape type.

+		Immutable
st_nrings(geometry: geometry) → int

Returns the number of rings in a Polygon Geometry. Returns 0 if the shape is not a Polygon.

+		Immutable
st_numgeometries(geometry: geometry) → int

Returns the number of shapes inside a given Geometry.

+		Immutable
st_numinteriorring(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numinteriorrings(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numpoints(geometry: geometry) → int

Returns the number of points in a LineString. Returns NULL if the Geometry is not a LineString.

+		Immutable
st_orderingequals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is exactly equal to geometry_b, having all coordinates in the same order, as well as the same type, SRID, bounding box, and so on.

+		Immutable
st_orientedenvelope(geometry: geometry) → geometry

Returns a minimum rotated rectangle enclosing a geometry. +Note that more than one minimum rotated rectangle may exist. +May return a Point or LineString in the case of degenerate inputs.

+		Immutable
st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_perimeter(geography: geography) → float

Returns the perimeter of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geography: geography, use_spheroid: bool) → float

Returns the perimeter of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_perimeter2d(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_point(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_pointfromgeohash(geohash: string) → geometry

Return a POINT Geometry from a GeoHash string with max precision.

+		Immutable
st_pointfromgeohash(geohash: string, precision: int) → geometry

Return a POINT Geometry from a GeoHash string with supplied precision.

+		Immutable
st_pointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Point, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_pointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointinsidecircle(geometry: geometry, x_coord: float, y_coord: float, radius: float) → bool

Returns the true if the geometry is a point and is inside the circle. Returns false otherwise.

+		Immutable
st_pointn(geometry: geometry, n: int) → geometry

Returns the n-th Point of a LineString (1-indexed). Returns NULL if out of bounds or not a LineString.

+		Immutable
st_pointonsurface(geometry: geometry) → geometry

Returns a point that intersects with the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_points(geometry: geometry) → geometry

Returns all coordinates in the given Geometry as a MultiPoint, including duplicates.

+		Immutable
st_polyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygon(geometry: geometry, srid: int) → geometry

Returns a new Polygon from the given LineString and sets its SRID. It is equivalent to ST_MakePolygon with a single argument followed by ST_SetSRID.

+		Immutable
st_polygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_project(geography: geography, distance: float, azimuth: float) → geography

Returns a point projected from a start point along a geodesic using a given distance and azimuth (bearing). +This is known as the direct geodesic problem.

+

The distance is given in meters. Negative values are supported.

+

The azimuth (also known as heading or bearing) is given in radians. It is measured clockwise from true north (azimuth zero). +East is azimuth π/2 (90 degrees); south is azimuth π (180 degrees); west is azimuth 3π/2 (270 degrees). +Negative azimuth values and values greater than 2π (360 degrees) are supported.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, bnr: int) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b using the given boundary node rule (1:OGC/MOD2, 2:Endpoint, 3:MultivalentEndpoint, 4:MonovalentEndpoint).

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, pattern: string) → bool

Returns whether the DE-9IM spatial relation between geometry_a and geometry_b matches the DE-9IM pattern.

+

This function utilizes the GEOS module.

+		Immutable
st_relatematch(intersection_matrix: string, pattern: string) → bool

Returns whether the given DE-9IM intersection matrix satisfies the given pattern.

+		Immutable
st_removepoint(line_string: geometry, index: int) → geometry

Removes the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_removerepeatedpoints(geometry: geometry) → geometry

Returns a geometry with repeated points removed.

+		Immutable
st_removerepeatedpoints(geometry: geometry, tolerance: float) → geometry

Returns a geometry with repeated points removed, within the given distance tolerance.

+		Immutable
st_reverse(geometry: geometry) → geometry

Returns a modified geometry by reversing the order of its vertices.

+		Immutable
st_rotate(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_point: geometry) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_x: float, origin_y: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotatex(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the x axis by a rotation angle.

+		Immutable
st_rotatey(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the y axis by a rotation angle.

+		Immutable
st_rotatez(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the z axis by a rotation angle.

+		Immutable
st_s2covering(geography: geography) → geography

Returns a geography which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geography: geography, settings: string) → geography

Returns a geography which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geography, 's2_max_level=15,s2_level_mod=3').

+		Immutable
st_s2covering(geometry: geometry) → geometry

Returns a geometry which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geometry: geometry, settings: string) → geometry

Returns a geometry which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geometry, 's2_max_level=15,s2_level_mod=3')

+		Immutable
st_scale(g: geometry, factor: geometry) → geometry

Returns a modified Geometry scaled by taking in a Geometry as the factor.

+		Immutable
st_scale(g: geometry, factor: geometry, origin: geometry) → geometry

Returns a modified Geometry scaled by the Geometry factor relative to a false origin.

+		Immutable
st_scale(geometry: geometry, x_factor: float, y_factor: float) → geometry

Returns a modified Geometry scaled by the given factors.

+		Immutable
st_segmentize(geography: geography, max_segment_length_meters: float) → geography

Returns a modified Geography having no segment longer than the given max_segment_length meters.

+

The calculations are done on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_segmentize(geometry: geometry, max_segment_length: float) → geometry

Returns a modified Geometry having no segment longer than the given max_segment_length. Length units are in units of spatial reference.

+		Immutable
st_setpoint(line_string: geometry, index: int, point: geometry) → geometry

Sets the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_setsrid(geography: geography, srid: int) → geography

Sets a Geography to a new SRID without transforming the coordinates.

+		Immutable
st_setsrid(geometry: geometry, srid: int) → geometry

Sets a Geometry to a new SRID without transforming the coordinates.

+		Immutable
st_sharedpaths(geometry_a: geometry, geometry_b: geometry) → geometry

Returns a collection containing paths shared by the two input geometries.

+

Those going in the same direction are in the first element of the collection, +those going in the opposite direction are in the second element. +The paths themselves are given in the direction of the first geometry.

+		Immutable
st_shiftlongitude(geometry: geometry) → geometry

Returns a modified version of a geometry in which the longitude (X coordinate) of each point is incremented by 360 if it is <0 and decremented by 360 if it is >180. The result is only meaningful if the coordinates are in longitude/latitude.

+		Immutable
st_shortestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the minimum distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the minimum distance between the geometry’s vertexes. The function will return the shortest line that was discovered first when comparing minimum distances if more than one is found.

+		Immutable
st_simplify(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm.

+

This function utilizes the GEOS module.

+		Immutable
st_simplify(geometry: geometry, tolerance: float, preserve_collapsed: bool) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, retaining objects that would be too small given the tolerance if preserve_collapsed is set to true.

+		Immutable
st_simplifypreservetopology(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, avoiding the creation of invalid geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_snap(input: geometry, target: geometry, tolerance: float) → geometry

Snaps the vertices and segments of input geometry the target geometry’s vertices. +Tolerance is used to control where snapping is performed. The result geometry is the input geometry with the vertices snapped. +If no snapping occurs then the input geometry is returned unchanged.

+		Immutable
st_snaptogrid(geometry: geometry, origin: geometry, size_x: float, size_y: float, size_z: float, size_m: float) → geometry

Snap a geometry to a grid defined by the given origin and X, Y, Z, and M cell sizes. Any dimension with a 0 cell size will not be snapped.

+		Immutable
st_snaptogrid(geometry: geometry, origin_x: float, origin_y: float, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y based on an origin of (origin_x, origin_y).

+		Immutable
st_snaptogrid(geometry: geometry, size: float) → geometry

Snap a geometry to a grid of the given size. The specified size is only used to snap X and Y coordinates.

+		Immutable
st_snaptogrid(geometry: geometry, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y.

+		Immutable
st_srid(geography: geography) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geography as defined in spatial_ref_sys table.

+		Immutable
st_srid(geometry: geometry) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geometry as defined in spatial_ref_sys table.

+		Immutable
st_startpoint(geometry: geometry) → geometry

Returns the first point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_subdivide(geometry: geometry) → geometry

Returns a geometry divided into parts, where each part contains no more than 256 vertices.

+		Immutable
st_subdivide(geometry: geometry, max_vertices: int4) → geometry

Returns a geometry divided into parts, where each part contains no more than the number of vertices provided.

+		Immutable
st_summary(geography: geography) → string

Returns a text summary of the contents of the geography.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_summary(geometry: geometry) → string

Returns a text summary of the contents of the geometry.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_swapordinates(geometry: geometry, swap_ordinate_string: string) → geometry

Returns a version of the given geometry with given ordinates swapped. +The swap_ordinate_string parameter is a 2-character string naming the ordinates to swap. Valid names are: x, y, z and m.

+		Immutable
st_symdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_symmetricdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4, bounds: geometry) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4, bounds: geometry, margin: float) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, srid: int) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates. The supplied SRID is set on the new geometry.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, srid: int) → geometry

Transforms a geometry into the given SRID coordinate reference system by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system referenced by the projection text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float, delta_z: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_transscale(geometry: geometry, delta_x: float, delta_y: float, x_factor: float, y_factor: float) → geometry

Translates the geometry using the deltaX and deltaY args, then scales it using the XFactor, YFactor args, working in 2D only.

+		Immutable
st_unaryunion(geometry: geometry) → geometry

Returns a union of the components for any geometry or geometry collection provided. Dissolves boundaries of a multipolygon.

+		Immutable
st_voronoilines(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoipolygons(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_wkbtosql(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_wkttosql(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_x(geometry: geometry) → float

Returns the X coordinate of a geometry if it is a Point.

+		Immutable
st_xmax(box2d: box2d) → float

Returns the maximum X ordinate of a box2d.

+		Immutable
st_xmax(geometry: geometry) → float

Returns the maximum X ordinate of a geometry.

+		Immutable
st_xmin(box2d: box2d) → float

Returns the minimum X ordinate of a box2d.

+		Immutable
st_xmin(geometry: geometry) → float

Returns the minimum X ordinate of a geometry.

+		Immutable
st_y(geometry: geometry) → float

Returns the Y coordinate of a geometry if it is a Point.

+		Immutable
st_ymax(box2d: box2d) → float

Returns the maximum Y ordinate of a box2d.

+		Immutable
st_ymax(geometry: geometry) → float

Returns the maximum Y ordinate of a geometry.

+		Immutable
st_ymin(box2d: box2d) → float

Returns the minimum Y ordinate of a box2d.

+		Immutable
st_ymin(geometry: geometry) → float

Returns the minimum Y ordinate of a geometry.

+		Immutable
st_z(geometry: geometry) → float

Returns the Z coordinate of a geometry if it is a Point.

+		Immutable
st_zmflag(geometry: geometry) → int2

Returns a code based on the ZM coordinate dimension of a geometry (XY = 0, XYM = 1, XYZ = 2, XYZM = 3).

+		Immutable
+ +### String and byte functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ascii(val: string) → int

Returns the character code of the first character in val. Despite the name, the function supports Unicode too.

+		Immutable
bit_count(val: bytes) → int

Calculates the number of bits set used to represent val.

+		Immutable
bit_count(val: varbit) → int

Calculates the number of bits set used to represent val.

+		Immutable
bit_length(val: bytes) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: string) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
bitmask_and(a: string, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: string, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
btrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning or end of input (applies recursively).

+

For example, btrim('doggie', 'eod') returns ggi.

+		Immutable
btrim(val: string) → string

Removes all spaces from the beginning and end of val.

+		Immutable
char_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
char_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
character_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
character_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
chr(val: int) → string

Returns the character with the code given in val. Inverse function of ascii().

+		Immutable
compress(data: bytes, codec: string) → bytes

Compress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
concat(string...) → string

Concatenates a comma-separated list of strings.

+		Immutable
concat_ws(string...) → string

Uses the first argument as a separator between the concatenation of the subsequent arguments.

+

For example concat_ws('!','wow','great') returns wow!great.

+		Immutable
convert_from(str: bytes, enc: string) → string

Decode the bytes in str into a string using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
convert_to(str: string, enc: string) → bytes

Encode the string str as a byte array using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
decode(text: string, format: string) → bytes

Decodes data using format (hex / escape / base64).

+		Immutable
decompress(data: bytes, codec: string) → bytes

Decompress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
difference(source: string, target: string) → int

Convert two strings to their Soundex codes and report the number of matching code positions.

+		Immutable
encode(data: bytes, format: string) → string

Encodes data using format (hex / escape / base64).

+		Immutable
format(string, anyelement...) → string

Interprets the first argument as a format string similar to C sprintf and interpolates the remaining arguments.

+		Stable
from_ip(val: bytes) → string

Converts the byte string representation of an IP to its character string representation.

+		Immutable
from_uuid(val: bytes) → string

Converts the byte string representation of a UUID to its character string representation.

+		Immutable
get_bit(bit_string: varbit, index: int) → int

Extracts a bit at given index in the bit array.

+		Immutable
get_bit(byte_string: bytes, index: int) → int

Extracts a bit at the given index in the byte array.

+		Immutable
get_byte(byte_string: bytes, index: int) → int

Extracts a byte at the given index in the byte array.

+		Immutable
initcap(val: string) → string

Capitalizes the first letter of val.

+		Immutable
left(input: bytes, return_set: int) → bytes

Returns the first return_set bytes from input.

+		Immutable
left(input: string, return_set: int) → string

Returns the first return_set characters from input.

+		Immutable
length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
length(val: string) → int

Calculates the number of characters in val.

+		Immutable
length(val: varbit) → int

Calculates the number of bits in val.

+		Immutable
lower(val: string) → string

Converts all characters in val to their lower-case equivalents.

+		Immutable
lpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the left of string.If string is longer than length it is truncated.

+		Immutable
lpad(string: string, length: int, fill: string) → string

Pads string by adding fill to the left of string to make it length. If string is longer than length it is truncated.

+		Immutable
ltrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning (left-hand side) of input (applies recursively).

+

For example, ltrim('doggie', 'od') returns ggie.

+		Immutable
ltrim(val: string) → string

Removes all spaces from the beginning (left-hand side) of val.

+		Immutable
md5(bytes...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
md5(string...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
octet_length(val: bytes) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: string) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int) → string

Replaces characters in input with overlay_val starting at start_pos (begins at 1).

+

For example, overlay('doggie', 'CAT', 2) returns dCATie.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int, end_pos: int) → string

Deletes the characters in input between start_pos and end_pos (count starts at 1), and then insert overlay_val at start_pos.

+		Immutable
parse_date(string: string, datestyle: string) → date

Parses a date assuming it is in format specified by DateStyle.

+		Immutable
parse_date(val: string) → date

Parses a date assuming it is in MDY format.

+		Immutable
parse_ident(qualified_identifier: string) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. Extra characters after the last identifier are considered an error

+		Immutable
parse_ident(qualified_identifier: string, strict: bool) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. If strict is false, then extra characters after the last identifier are ignored.

+		Immutable
parse_interval(string: string, style: string) → interval

Convert a string to an interval using the given IntervalStyle.

+		Immutable
parse_interval(val: string) → interval

Convert a string to an interval assuming the Postgres IntervalStyle.

+		Immutable
parse_time(string: string, timestyle: string) → time

Parses a time assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_time(val: string) → time

Parses a time assuming the date (if any) is in MDY format.

+		Immutable
parse_timestamp(string: string, datestyle: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates formatted using the given DateStyle.

+		Immutable
parse_timestamp(val: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates are in MDY format.

+		Immutable
parse_timetz(string: string, timestyle: string) → timetz

Parses a timetz assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_timetz(val: string) → timetz

Parses a timetz assuming the date (if any) is in MDY format.

+		Immutable
prettify_statement(statement: string, line_width: int, align_mode: int, case_mode: int) → string

Prettifies a statement using a user-configured pretty-printing config. +Align mode values range from 0 - 3, representing no, partial, full, and extra alignment respectively. +Case mode values range between 0 - 1, representing lower casing and upper casing respectively.

+		Immutable
prettify_statement(val: string) → string

Prettifies a statement using a the default pretty-printing config.

+		Immutable
quote_ident(val: string) → string

Return val suitably quoted to serve as identifier in a SQL statement.

+		Immutable
quote_literal(val: string) → string

Return val suitably quoted to serve as string literal in a SQL statement.

+		Immutable
quote_literal(val: anyelement) → string

Coerce val to a string and then quote it as a literal.

+		Stable
quote_nullable(val: string) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Immutable
quote_nullable(val: anyelement) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Stable
regexp_extract(input: string, regex: string) → string

Returns the first match for the Regular Expression regex in input.

+		Immutable
regexp_replace(input: string, regex: string, replace: string) → string

Replaces matches for the Regular Expression regex in input with the Regular Expression replace.

+		Immutable
regexp_replace(input: string, regex: string, replace: string, flags: string) → string

Replaces matches for the regular expression regex in input with the regular expression replace using flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
repeat(input: string, repeat_counter: int) → string

Concatenates input repeat_counter number of times.

+

For example, repeat('dog', 2) returns dogdog.

+		Immutable
replace(input: string, find: string, replace: string) → string

Replaces all occurrences of find with replace in input

+		Immutable
reverse(val: string) → string

Reverses the order of the string’s characters.

+		Immutable
right(input: bytes, return_set: int) → bytes

Returns the last return_set bytes from input.

+		Immutable
right(input: string, return_set: int) → string

Returns the last return_set characters from input.

+		Immutable
rpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the right of string. If string is longer than length it is truncated.

+		Immutable
rpad(string: string, length: int, fill: string) → string

Pads string to length by adding fill to the right of string. If string is longer than length it is truncated.

+		Immutable
rtrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the end (right-hand side) of input (applies recursively).

+

For example, rtrim('doggie', 'ei') returns dogg.

+		Immutable
rtrim(val: string) → string

Removes all spaces from the end (right-hand side) of val.

+		Immutable
set_bit(bit_string: varbit, index: int, to_set: int) → varbit

Updates a bit at given index in the bit array.

+		Immutable
set_bit(byte_string: bytes, index: int, to_set: int) → bytes

Updates a bit at the given index in the byte array.

+		Immutable
set_byte(byte_string: bytes, index: int, to_set: int) → bytes

Updates a byte at the given index in the byte array.

+		Immutable
sha1(bytes...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha1(string...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha224(bytes...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha224(string...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha256(bytes...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha256(string...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha384(bytes...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha384(string...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha512(bytes...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
sha512(string...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
similar_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_to_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
split_part(input: string, delimiter: string, return_index_pos: int) → string

Splits input on delimiter and return the value in the return_index_pos position (starting at 1).

+

For example, split_part('123.456.789.0','.',3)returns 789.

+		Immutable
strpos(input: bytes, find: bytes) → int

Calculates the position where the byte subarray find begins in input.

+		Immutable
strpos(input: string, find: string) → int

Calculates the position where the string find begins in input.

+

For example, strpos('doggie', 'gie') returns 4.

+		Immutable
strpos(input: varbit, find: varbit) → int

Calculates the position where the bit subarray find begins in input.

+		Immutable
substr(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substr(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substr(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substring(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substring(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
to_char_with_style(date: date, datestyle: string) → string

Convert an date to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_char_with_style(interval: interval, style: string) → string

Convert an interval to a string using the given IntervalStyle.

+		Immutable
to_char_with_style(timestamp: timestamp, datestyle: string) → string

Convert an timestamp to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_english(val: int) → string

This function enunciates the value of its argument using English cardinals.

+		Immutable
to_hex(val: bytes) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: int) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: string) → string

Converts val to its hexadecimal representation.

+		Immutable
to_ip(val: string) → bytes

Converts the character string representation of an IP to its byte string representation.

+		Immutable
to_uuid(val: string) → bytes

Converts the character string representation of a UUID to its byte string representation.

+		Immutable
translate(input: string, find: string, replace: string) → string

In input, replaces the first character from find with the first character in replace; repeat for each character in find.

+

For example, translate('doggie', 'dog', '123'); returns 1233ie.

+		Immutable
ulid_to_uuid(val: string) → uuid

Converts a ULID string to its UUID-encoded representation.

+		Immutable
unaccent(val: string) → string

Removes accents (diacritic signs) from the text provided in val.

+		Immutable
upper(val: string) → string

Converts all characters in val to their to their upper-case equivalents.

+		Immutable
+ +### System info functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cluster_logical_timestamp() → decimal

Returns the logical time of the current transaction as +a CockroachDB HLC in decimal form.

+

Note that uses of this function disable server-side optimizations and +may increase either contention or retry errors, or both.

+

Returns an error if run in a transaction with an isolation level weaker than SERIALIZABLE.

+		Volatile
current_database() → string

Returns the current database.

+		Stable
current_schema() → string

Returns the current schema.

+		Stable
current_schemas(include_pg_catalog: bool) → string[]

Returns the valid schemas in the search path.

+		Stable
current_user() → string

Returns the current user. This function is provided for compatibility with PostgreSQL.

+		Stable
session_user() → string

Returns the session user. This function is provided for compatibility with PostgreSQL.

+		Stable
to_regclass(text: string) → regtype

Translates a textual relation name to its OID

+		Stable
to_regnamespace(text: string) → regtype

Translates a textual schema name to its OID

+		Stable
to_regproc(text: string) → regtype

Translates a textual function or procedure name to its OID

+		Stable
to_regprocedure(text: string) → regtype

Translates a textual function or procedure name(with argument types) to its OID

+		Stable
to_regrole(text: string) → regtype

Translates a textual role name to its OID

+		Stable
to_regtype(text: string) → regtype

Translates a textual type name to its OID

+		Stable
version() → string

Returns the node’s version of CockroachDB.

+		Volatile
+ +### TIMETZ functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
current_time() → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time() → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_time(precision: int) → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time(precision: int) → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → timetz

Returns the current transaction’s time with time zone.

+		Stable
localtime(precision: int) → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime(precision: int) → timetz

Returns the current transaction’s time with time zone.

+		Stable
+ +### Trigrams functions + + + + + + +
Function → ReturnsDescriptionVolatility
show_trgm(input: string) → string[]

Returns an array of all the trigrams in the given string.

+		Immutable
similarity(left: string, right: string) → float

Returns a number that indicates how similar the two arguments are. The range of the result is zero (indicating that the two strings are completely dissimilar) to one (indicating that the two strings are identical).

+		Immutable
+ +### UUID functions + + + + + +
Function → ReturnsDescriptionVolatility
uuid_to_ulid(val: uuid) → string

Converts a UUID-encoded ULID to its string representation.

+		Immutable
+ +### Compatibility functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
col_description(table_oid: oid, column_number: int) → string

Returns the comment for a table column, which is specified by the OID of its table and its column number. (obj_description cannot be used for table columns, since columns do not have OIDs of their own.)

+		Stable
current_setting(setting_name: string) → string

System info

+		Stable
current_setting(setting_name: string, missing_ok: bool) → string

System info

+		Stable
format_type(type_oid: oid, typemod: int) → string

Returns the SQL name of a data type that is identified by its type OID and possibly a type modifier. Currently, the type modifier is ignored.

+		Stable
getdatabaseencoding() → string

Returns the current encoding name used by the database.

+		Stable
has_any_column_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_column_privilege(table: string, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: string, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_database_privilege(database: string, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(database: oid, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(user: string, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: string, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_foreign_data_wrapper_privilege(fdw: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(fdw: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_function_privilege(function: string, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(function: oid, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(user: string, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: string, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_language_privilege(language: string, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(language: oid, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(user: string, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: string, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_schema_privilege(schema: string, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(schema: oid, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_sequence_privilege(sequence: string, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(sequence: oid, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_server_privilege(server: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(server: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_table_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_tablespace_privilege(tablespace: string, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(tablespace: oid, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_type_privilege(type: string, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(type: oid, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(user: string, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: string, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
information_schema._pg_numeric_precision(typid: oid, typmod: int4) → int

Returns the precision of the given type with type modifier

+		Immutable
information_schema._pg_numeric_precision_radix(typid: oid, typmod: int4) → int

Returns the radix of the given type with type modifier

+		Immutable
information_schema._pg_numeric_scale(typid: oid, typmod: int4) → int

Returns the scale of the given type with type modifier

+		Immutable
nameconcatoid(name: string, oid: oid) → name

Used in the information_schema to produce specific_name columns, which are supposed to be unique per schema. The result is the same as ($1::text || ‘_’ || $2::text)::name except that, if it would not fit in 63 characters, we make it do so by truncating the name input (not the oid).

+		Immutable
obj_description(object_oid: oid) → string

Returns the comment for a database object specified by its OID alone. This is deprecated since there is no guarantee that OIDs are unique across different system catalogs; therefore, the wrong comment might be returned.

+		Stable
obj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a database object specified by its OID and the name of the containing system catalog. For example, obj_description(123456, ‘pg_class’) would retrieve the comment for the table with OID 123456.

+		Stable
oidvectortypes(vector: oidvector) → string

Generates a comma seperated string of type names from an oidvector.

+		Stable
pg_backend_pid() → int

Returns a numerical ID attached to this session. This ID is part of the query cancellation key used by the wire protocol. This function was only added for compatibility, and unlike in Postgres, the returned value does not correspond to a real process ID.

+		Stable
pg_collation_for(str: anyelement) → string

Returns the collation of the argument

+		Stable
pg_column_is_updatable(reloid: oid, attnum: int2, include_triggers: bool) → bool

Returns whether the given column can be updated.

+		Stable
pg_column_size(anyelement...) → int

Return size in bytes of the column provided as an argument

+		Immutable
pg_function_is_visible(oid: oid) → bool

Returns whether the function with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_get_function_arg_default(func_oid: oid, arg_num: int4) → string

Get textual representation of a function argument’s default value. The second argument of this function is the argument number among all arguments (i.e. proallargtypes, not proargtypes), starting with 1, because that’s how information_schema.sql uses it. Currently, this always returns NULL, since CockroachDB does not support default values.

+		Stable
pg_get_function_arguments(func_oid: oid) → string

Returns the argument list (with defaults) necessary to identify a function, in the form it would need to appear in within CREATE FUNCTION.

+		Stable
pg_get_function_identity_arguments(func_oid: oid) → string

Returns the argument list (without defaults) necessary to identify a function, in the form it would need to appear in within ALTER FUNCTION, for instance.

+		Stable
pg_get_function_result(func_oid: oid) → string

Returns the types of the result of the specified function.

+		Stable
pg_get_functiondef(func_oid: oid) → string

For user-defined functions, returns the definition of the specified function. For builtin functions, returns the name of the function.

+		Stable
pg_get_indexdef(index_oid: oid) → string

Gets the CREATE INDEX command for index

+		Stable
pg_get_indexdef(index_oid: oid, column_no: int, pretty_bool: bool) → string

Gets the CREATE INDEX command for index, or definition of just one index column when given a non-zero column number

+		Stable
pg_get_serial_sequence(table_name: string, column_name: string) → string

Returns the name of the sequence used by the given column_name in the table table_name.

+		Stable
pg_get_viewdef(view_oid: oid) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_get_viewdef(view_oid: oid, pretty_bool: bool) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_has_role(role: string, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(role: oid, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(user: string, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: string, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_is_other_temp_schema(oid: oid) → bool

Returns true if the given OID is the OID of another session’s temporary schema. (This can be useful, for example, to exclude other sessions’ temporary tables from a catalog display.)

+		Stable
pg_my_temp_schema() → oid

Returns the OID of the current session’s temporary schema, or zero if it has none (because it has not created any temporary tables).

+		Stable
pg_relation_is_updatable(reloid: oid, include_triggers: bool) → int4

Returns the update events the relation supports.

+		Stable
pg_sequence_last_value(sequence_oid: oid) → int

Returns the last value generated by a sequence, or NULL if the sequence has not been used yet.

+		Volatile
pg_sleep(seconds: float) → bool

pg_sleep makes the current session’s process sleep until seconds seconds have elapsed. seconds is a value of type double precision, so fractional-second delays can be specified.

+		Volatile
pg_table_is_visible(oid: oid) → bool

Returns whether the table with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_type_is_visible(oid: oid) → bool

Returns whether the type with the given OID belongs to one of the schemas on the search path.

+		Stable
set_config(setting_name: string, new_value: string, is_local: bool) → string

System info

+		Volatile
shobj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a shared database object specified by its OID and the name of the containing system catalog. This is just like obj_description except that it is used for retrieving comments on shared objects (e.g. databases).

+		Stable
+ diff --git a/src/current/_includes/cockroach-generated/release-24.2/sql/operators.md b/src/current/_includes/cockroach-generated/release-24.2/sql/operators.md new file mode 100644 index 00000000000..47027b064fe --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.2/sql/operators.md @@ -0,0 +1,658 @@ + + + + + +
#Return
int # intint
varbit # varbitvarbit
+ + + + +
#>Return
jsonb #> string[]jsonb
+ + + + +
#>>Return
jsonb #>> string[]string
+ + + + + + + + + +
%Return
decimal % decimaldecimal
decimal % intdecimal
float % floatfloat
int % decimaldecimal
int % intint
string % stringbool
+ + + + + + +
&Return
inet & inetinet
int & intint
varbit & varbitvarbit
+ + + + + + + + + +
&&Return
anyelement && anyelementbool
box2d && box2dbool
box2d && geometrybool
geometry && box2dbool
geometry && geometrybool
inet && inetbool
+ + + + + + + + + + + + + + + +
*Return
decimal * decimaldecimal
decimal * intdecimal
decimal * intervalinterval
float * floatfloat
float * intervalinterval
int * decimaldecimal
int * intint
int * intervalinterval
interval * decimalinterval
interval * floatinterval
interval * intinterval
vector * vectorvector
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Return
+decimaldecimal
+floatfloat
+intint
+intervalinterval
date + intdate
date + intervaltimestamp
date + timetimestamp
date + timetztimestamptz
decimal + decimaldecimal
decimal + intdecimal
decimal + pg_lsnpg_lsn
float + floatfloat
inet + intinet
int + datedate
int + decimaldecimal
int + inetinet
int + intint
interval + datetimestamp
interval + intervalinterval
interval + timetime
interval + timestamptimestamp
interval + timestamptztimestamptz
interval + timetztimetz
pg_lsn + decimalpg_lsn
time + datetimestamp
time + intervaltime
timestamp + intervaltimestamp
timestamptz + intervaltimestamptz
timetz + datetimestamptz
timetz + intervaltimetz
vector + vectorvector
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
-Return
-decimaldecimal
-floatfloat
-intint
-intervalinterval
date - dateint
date - intdate
date - intervaltimestamp
date - timetimestamp
decimal - decimaldecimal
decimal - intdecimal
float - floatfloat
inet - inetint
inet - intinet
int - decimaldecimal
int - intint
interval - intervalinterval
jsonb - intjsonb
jsonb - stringjsonb
jsonb - string[]jsonb
pg_lsn - decimalpg_lsn
pg_lsn - pg_lsndecimal
time - intervaltime
time - timeinterval
timestamp - intervaltimestamp
timestamp - timestampinterval
timestamp - timestamptzinterval
timestamptz - intervaltimestamptz
timestamptz - timestampinterval
timestamptz - timestamptzinterval
timetz - intervaltimetz
vector - vectorvector
+ + + + + +
->Return
jsonb -> intjsonb
jsonb -> stringjsonb
+ + + + + +
->>Return
jsonb ->> intstring
jsonb ->> stringstring
+ + + + + + + + + + +
/Return
decimal / decimaldecimal
decimal / intdecimal
float / floatfloat
int / decimaldecimal
int / intdecimal
interval / floatinterval
interval / intinterval
+ + + + + + + + +
//Return
decimal // decimaldecimal
decimal // intdecimal
float // floatfloat
int // decimaldecimal
int // intint
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<Return
anyenum < anyenumbool
bool < boolbool
bool[] < bool[]bool
box2d < box2dbool
bpchar < bpcharbool
bytes < bytesbool
bytes[] < bytes[]bool
collatedstring < collatedstringbool
date < datebool
date < timestampbool
date < timestamptzbool
date[] < date[]bool
decimal < decimalbool
decimal < floatbool
decimal < intbool
decimal[] < decimal[]bool
float < decimalbool
float < floatbool
float < intbool
float[] < float[]bool
geography < geographybool
geometry < geometrybool
inet < inetbool
inet[] < inet[]bool
int < decimalbool
int < floatbool
int < intbool
int < oidbool
int[] < int[]bool
interval < intervalbool
interval[] < interval[]bool
jsonb < jsonbbool
oid < intbool
oid < oidbool
pg_lsn < pg_lsnbool
refcursor < refcursorbool
string < stringbool
string[] < string[]bool
time < timebool
time < timetzbool
time[] < time[]bool
timestamp < datebool
timestamp < timestampbool
timestamp < timestamptzbool
timestamp[] < timestamp[]bool
timestamptz < datebool
timestamptz < timestampbool
timestamptz < timestamptzbool
timestamptz < timestamptzbool
timetz < timebool
timetz < timetzbool
tuple < tuplebool
uuid < uuidbool
uuid[] < uuid[]bool
varbit < varbitbool
vector < vectorbool
+ + + + +
<#>Return
vector <#> vectorfloat
+ + + + +
<->Return
vector <-> vectorfloat
+ + + + + + +
<<Return
inet << inetbool
int << intint
varbit << intvarbit
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<=Return
anyenum <= anyenumbool
bool <= boolbool
bool[] <= bool[]bool
box2d <= box2dbool
bpchar <= bpcharbool
bytes <= bytesbool
bytes[] <= bytes[]bool
collatedstring <= collatedstringbool
date <= datebool
date <= timestampbool
date <= timestamptzbool
date[] <= date[]bool
decimal <= decimalbool
decimal <= floatbool
decimal <= intbool
decimal[] <= decimal[]bool
float <= decimalbool
float <= floatbool
float <= intbool
float[] <= float[]bool
geography <= geographybool
geometry <= geometrybool
inet <= inetbool
inet[] <= inet[]bool
int <= decimalbool
int <= floatbool
int <= intbool
int <= oidbool
int[] <= int[]bool
interval <= intervalbool
interval[] <= interval[]bool
jsonb <= jsonbbool
oid <= intbool
oid <= oidbool
pg_lsn <= pg_lsnbool
refcursor <= refcursorbool
string <= stringbool
string[] <= string[]bool
time <= timebool
time <= timetzbool
time[] <= time[]bool
timestamp <= datebool
timestamp <= timestampbool
timestamp <= timestamptzbool
timestamp[] <= timestamp[]bool
timestamptz <= datebool
timestamptz <= timestampbool
timestamptz <= timestamptzbool
timestamptz <= timestamptzbool
timetz <= timebool
timetz <= timetzbool
tuple <= tuplebool
uuid <= uuidbool
uuid[] <= uuid[]bool
varbit <= varbitbool
vector <= vectorbool
+ + + + +
<=>Return
vector <=> vectorfloat
+ + + + + +
<@Return
anyelement <@ anyelementbool
jsonb <@ jsonbbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
=Return
anyenum = anyenumbool
bool = boolbool
bool[] = bool[]bool
box2d = box2dbool
bpchar = bpcharbool
bytes = bytesbool
bytes[] = bytes[]bool
collatedstring = collatedstringbool
date = datebool
date = timestampbool
date = timestamptzbool
date[] = date[]bool
decimal = decimalbool
decimal = floatbool
decimal = intbool
decimal[] = decimal[]bool
float = decimalbool
float = floatbool
float = intbool
float[] = float[]bool
geography = geographybool
geometry = geometrybool
inet = inetbool
inet[] = inet[]bool
int = decimalbool
int = floatbool
int = intbool
int = oidbool
int[] = int[]bool
interval = intervalbool
interval[] = interval[]bool
jsonb = jsonbbool
oid = intbool
oid = oidbool
pg_lsn = pg_lsnbool
refcursor = refcursorbool
string = stringbool
string[] = string[]bool
time = timebool
time = timetzbool
time[] = time[]bool
timestamp = datebool
timestamp = timestampbool
timestamp = timestamptzbool
timestamp[] = timestamp[]bool
timestamptz = datebool
timestamptz = timestampbool
timestamptz = timestamptzbool
timestamptz = timestamptzbool
timetz = timebool
timetz = timetzbool
tsquery = tsquerybool
tsvector = tsvectorbool
tuple = tuplebool
uuid = uuidbool
uuid[] = uuid[]bool
varbit = varbitbool
vector = vectorbool
+ + + + + + +
>>Return
inet >> inetbool
int >> intint
varbit >> intvarbit
+ + + + +
?Return
jsonb ? stringbool
+ + + + +
?&Return
jsonb ?& string[]bool
+ + + + +
?|Return
jsonb ?| string[]bool
+ + + + + +
@>Return
anyelement @> anyelementbool
jsonb @> jsonbbool
+ + + + + +
@@Return
tsquery @@ tsvectorbool
tsvector @@ tsquerybool
+ + + + +
ILIKEReturn
string ILIKE stringbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
INReturn
anyenum IN tuplebool
bool IN tuplebool
box2d IN tuplebool
bpchar IN tuplebool
bytes IN tuplebool
collatedstring IN tuplebool
date IN tuplebool
decimal IN tuplebool
float IN tuplebool
geography IN tuplebool
geometry IN tuplebool
inet IN tuplebool
int IN tuplebool
interval IN tuplebool
jsonb IN tuplebool
oid IN tuplebool
pg_lsn IN tuplebool
refcursor IN tuplebool
string IN tuplebool
time IN tuplebool
timestamp IN tuplebool
timestamptz IN tuplebool
timetz IN tuplebool
tuple IN tuplebool
uuid IN tuplebool
varbit IN tuplebool
vector IN tuplebool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IS NOT DISTINCT FROMReturn
anyelement IS NOT DISTINCT FROM unknownbool
anyenum IS NOT DISTINCT FROM anyenumbool
bool IS NOT DISTINCT FROM boolbool
bool[] IS NOT DISTINCT FROM bool[]bool
box2d IS NOT DISTINCT FROM box2dbool
bpchar IS NOT DISTINCT FROM bpcharbool
bytes IS NOT DISTINCT FROM bytesbool
bytes[] IS NOT DISTINCT FROM bytes[]bool
collatedstring IS NOT DISTINCT FROM collatedstringbool
date IS NOT DISTINCT FROM datebool
date IS NOT DISTINCT FROM timestampbool
date IS NOT DISTINCT FROM timestamptzbool
date[] IS NOT DISTINCT FROM date[]bool
decimal IS NOT DISTINCT FROM decimalbool
decimal IS NOT DISTINCT FROM floatbool
decimal IS NOT DISTINCT FROM intbool
decimal[] IS NOT DISTINCT FROM decimal[]bool
float IS NOT DISTINCT FROM decimalbool
float IS NOT DISTINCT FROM floatbool
float IS NOT DISTINCT FROM intbool
float[] IS NOT DISTINCT FROM float[]bool
geography IS NOT DISTINCT FROM geographybool
geometry IS NOT DISTINCT FROM geometrybool
inet IS NOT DISTINCT FROM inetbool
inet[] IS NOT DISTINCT FROM inet[]bool
int IS NOT DISTINCT FROM decimalbool
int IS NOT DISTINCT FROM floatbool
int IS NOT DISTINCT FROM intbool
int IS NOT DISTINCT FROM oidbool
int[] IS NOT DISTINCT FROM int[]bool
interval IS NOT DISTINCT FROM intervalbool
interval[] IS NOT DISTINCT FROM interval[]bool
jsonb IS NOT DISTINCT FROM jsonbbool
oid IS NOT DISTINCT FROM intbool
oid IS NOT DISTINCT FROM oidbool
pg_lsn IS NOT DISTINCT FROM pg_lsnbool
refcursor IS NOT DISTINCT FROM refcursorbool
string IS NOT DISTINCT FROM stringbool
string[] IS NOT DISTINCT FROM string[]bool
time IS NOT DISTINCT FROM timebool
time IS NOT DISTINCT FROM timetzbool
time[] IS NOT DISTINCT FROM time[]bool
timestamp IS NOT DISTINCT FROM datebool
timestamp IS NOT DISTINCT FROM timestampbool
timestamp IS NOT DISTINCT FROM timestamptzbool
timestamp[] IS NOT DISTINCT FROM timestamp[]bool
timestamptz IS NOT DISTINCT FROM datebool
timestamptz IS NOT DISTINCT FROM timestampbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timetz IS NOT DISTINCT FROM timebool
timetz IS NOT DISTINCT FROM timetzbool
tsquery IS NOT DISTINCT FROM tsquerybool
tsvector IS NOT DISTINCT FROM tsvectorbool
tuple IS NOT DISTINCT FROM tuplebool
unknown IS NOT DISTINCT FROM unknownbool
unknown IS NOT DISTINCT FROM voidbool
uuid IS NOT DISTINCT FROM uuidbool
uuid[] IS NOT DISTINCT FROM uuid[]bool
varbit IS NOT DISTINCT FROM varbitbool
vector IS NOT DISTINCT FROM vectorbool
void IS NOT DISTINCT FROM unknownbool
+ + + + +
LIKEReturn
string LIKE stringbool
+ + + + +
SIMILAR TOReturn
string SIMILAR TO stringbool
+ + + + + + + + +
^Return
decimal ^ decimaldecimal
decimal ^ intdecimal
float ^ floatfloat
int ^ decimaldecimal
int ^ intint
+ + + + + + +
|Return
inet | inetinet
int | intint
varbit | varbitvarbit
+ + + + + +
|/Return
|/decimaldecimal
|/floatfloat
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
||Return
bool || bool[]bool[]
bool || stringstring
bool[] || boolbool[]
bool[] || bool[]bool[]
box2d || box2dbox2d
box2d || stringstring
bytes || bytesbytes
bytes || bytes[]bytes[]
bytes[] || bytesbytes[]
bytes[] || bytes[]bytes[]
date || date[]date[]
date || stringstring
date[] || datedate[]
date[] || date[]date[]
decimal || decimal[]decimal[]
decimal || stringstring
decimal[] || decimaldecimal[]
decimal[] || decimal[]decimal[]
float || float[]float[]
float || stringstring
float[] || floatfloat[]
float[] || float[]float[]
geography || geographygeography
geography || stringstring
geometry || geometrygeometry
geometry || stringstring
inet || inet[]inet[]
inet || stringstring
inet[] || inetinet[]
inet[] || inet[]inet[]
int || int[]int[]
int || stringstring
int[] || intint[]
int[] || int[]int[]
interval || interval[]interval[]
interval || stringstring
interval[] || intervalinterval[]
interval[] || interval[]interval[]
jsonb || jsonbjsonb
jsonb || stringstring
oid || oidoid
oid || stringstring
pg_lsn || pg_lsnpg_lsn
pg_lsn || stringstring
refcursor || refcursorrefcursor
refcursor || stringstring
string || boolstring
string || box2dstring
string || datestring
string || decimalstring
string || floatstring
string || geographystring
string || geometrystring
string || inetstring
string || intstring
string || intervalstring
string || jsonbstring
string || oidstring
string || pg_lsnstring
string || refcursorstring
string || stringstring
string || string[]string[]
string || timestring
string || timestampstring
string || timestamptzstring
string || timetzstring
string || tuplestring
string || uuidstring
string || varbitstring
string[] || stringstring[]
string[] || string[]string[]
time || stringstring
time || time[]time[]
time[] || timetime[]
time[] || time[]time[]
timestamp || stringstring
timestamp || timestamp[]timestamp[]
timestamp[] || timestamptimestamp[]
timestamp[] || timestamp[]timestamp[]
timestamptz || stringstring
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timetz || stringstring
timetz || timetztimetz
tuple || stringstring
uuid || stringstring
uuid || uuid[]uuid[]
uuid[] || uuiduuid[]
uuid[] || uuid[]uuid[]
varbit || stringstring
varbit || varbitvarbit
+ + + + + +
||/Return
||/decimaldecimal
||/floatfloat
+ + + + + + + + + + + +
~Return
~inetinet
~intint
~varbitvarbit
box2d ~ box2dbool
box2d ~ geometrybool
geometry ~ box2dbool
geometry ~ geometrybool
string ~ stringbool
+ + + + +
~*Return
string ~* stringbool
diff --git a/src/current/_includes/cockroach-generated/release-24.2/sql/window_functions.md b/src/current/_includes/cockroach-generated/release-24.2/sql/window_functions.md new file mode 100644 index 00000000000..e1032ff82de --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.2/sql/window_functions.md @@ -0,0 +1,413 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cume_dist() → float

Calculates the relative rank of the current row: (number of rows preceding or peer with current row) / (total rows).

+		Immutable
dense_rank() → int

Calculates the rank of the current row without gaps; this function counts peer groups.

+		Immutable
first_value(val: bool) → bool

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: bytes) → bytes

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: date) → date

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: decimal) → decimal

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: float) → float

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: inet) → inet

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: int) → int

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: interval) → interval

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: string) → string

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: time) → time

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: uuid) → uuid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: box2d) → box2d

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geography) → geography

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geometry) → geometry

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: oid) → oid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timetz) → timetz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: varbit) → varbit

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
lag(val: bool) → bool

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: bytes) → bytes

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: date) → date

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: date, n: int) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: decimal) → decimal

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: float) → float

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: float, n: int) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: inet) → inet

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: int) → int

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: int, n: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: interval) → interval

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: string) → string

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: string, n: int) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: time) → time

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: time, n: int) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamp) → timestamp

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz) → timestamptz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: uuid) → uuid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: box2d) → box2d

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geography) → geography

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geometry) → geometry

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: jsonb) → jsonb

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: oid) → oid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn) → pg_lsn

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: refcursor) → refcursor

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timetz) → timetz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: varbit) → varbit

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
last_value(val: bool) → bool

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: bytes) → bytes

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: date) → date

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: decimal) → decimal

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: float) → float

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: inet) → inet

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: int) → int

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: interval) → interval

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: string) → string

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: time) → time

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: uuid) → uuid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: box2d) → box2d

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geography) → geography

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geometry) → geometry

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: oid) → oid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timetz) → timetz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: varbit) → varbit

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
lead(val: bool) → bool

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: bytes) → bytes

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: date) → date

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: date, n: int) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: decimal) → decimal

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: float) → float

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: float, n: int) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: inet) → inet

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: int) → int

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: int, n: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: interval) → interval

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: string) → string

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: string, n: int) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: time) → time

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: time, n: int) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamp) → timestamp

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz) → timestamptz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: uuid) → uuid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: box2d) → box2d

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geography) → geography

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geometry) → geometry

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: jsonb) → jsonb

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: oid) → oid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn) → pg_lsn

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: refcursor) → refcursor

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timetz) → timetz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: varbit) → varbit

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
nth_value(val: bool, n: int) → bool

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: bytes, n: int) → bytes

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: date, n: int) → date

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: decimal, n: int) → decimal

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: float, n: int) → float

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: inet, n: int) → inet

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: int, n: int) → int

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: interval, n: int) → interval

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: string, n: int) → string

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: time, n: int) → time

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: uuid, n: int) → uuid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: box2d, n: int) → box2d

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geography, n: int) → geography

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geometry, n: int) → geometry

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: oid, n: int) → oid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timetz, n: int) → timetz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: varbit, n: int) → varbit

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
ntile(n: int) → int

Calculates an integer ranging from 1 to n, dividing the partition as equally as possible.

+		Immutable
percent_rank() → float

Calculates the relative rank of the current row: (rank - 1) / (total rows - 1).

+		Immutable
rank() → int

Calculates the rank of the current row with gaps; same as row_number of its first peer.

+		Immutable
row_number() → int

Calculates the number of the current row within its partition, counting from 1.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-24.3/eventlog.md b/src/current/_includes/cockroach-generated/release-24.3/eventlog.md new file mode 100644 index 00000000000..25a64aec4cf --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.3/eventlog.md @@ -0,0 +1,3436 @@ +Certain notable events are reported using a structured format. +Commonly, these notable events are also copied to the table +`system.eventlog`, unless the cluster setting +`server.eventlog.enabled` is unset. + +Additionally, notable events are copied to specific external logging +channels in log messages, where they can be collected for further processing. + +The sections below document the possible notable event types +in this version of CockroachDB. For each event type, a table +documents the possible fields. A field may be omitted from +an event if its value is empty or zero. + +A field is also considered "Sensitive" if it may contain +application-specific information or personally identifiable information (PII). In that case, +the copy of the event sent to the external logging channel +will contain redaction markers in a format that is compatible +with the redaction facilities in [`cockroach debug zip`](cockroach-debug-zip.html) +and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html), +provided the `redactable` functionality is enabled on the logging sink. + +Events not documented on this page will have an unstructured format in log messages. + +## Changefeed telemetry events + +Events in this category pertain to changefeed usage and metrics. + +Events in this category are logged to the `TELEMETRY` channel. + + +### `changefeed_emitted_bytes` + +An event of type `changefeed_emitted_bytes` is an event representing the bytes emitted by a changefeed over an interval. + + +| Field | Description | Sensitive | +|--|--|--| +| `EmittedBytes` | The number of bytes emitted. | no | +| `EmittedMessages` | The number of messages emitted. | no | +| `LoggingInterval` | The time period in nanoseconds between emitting telemetry events of this type (per-aggregator). | no | +| `Closing` | Flag to indicate that the changefeed is closing. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `changefeed_failed` + +An event of type `changefeed_failed` is an event for any changefeed failure since the plan hook +was triggered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FailureType` | The reason / environment with which the changefeed failed (ex: connection_closed, changefeed_behind). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `create_changefeed` + +An event of type `create_changefeed` is an event for any CREATE CHANGEFEED query that +successfully starts running. Failed CREATE statements will show up as +ChangefeedFailed events. + + +| Field | Description | Sensitive | +|--|--|--| +| `Transformation` | Flag representing whether the changefeed is using CDC queries. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +## Cluster-level events + +Events in this category pertain to an entire cluster and are +not relative to any particular tenant. + +In a multi-tenant setup, the `system.eventlog` table for individual +tenants cannot contain a copy of cluster-level events; conversely, +the `system.eventlog` table in the system tenant cannot contain the +SQL-level events for individual tenants. + +Events in this category are logged to the `OPS` channel. + + +### `certs_reload` + +An event of type `certs_reload` is recorded when the TLS certificates are +reloaded/rotated from disk. + + +| Field | Description | Sensitive | +|--|--|--| +| `Success` | Whether the operation completed without errors. | no | +| `ErrorMessage` | If an error was encountered, the text of the error. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `disk_slowness_cleared` + +An event of type `disk_slowness_cleared` is recorded when disk slowness in a store has cleared. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `disk_slowness_detected` + +An event of type `disk_slowness_detected` is recorded when a store observes disk slowness +events. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `node_decommissioned` + +An event of type `node_decommissioned` is recorded when a node is marked as +decommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_decommissioning` + +An event of type `node_decommissioning` is recorded when a node is marked as +decommissioning. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_join` + +An event of type `node_join` is recorded when a node joins the cluster. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_recommissioned` + +An event of type `node_recommissioned` is recorded when a decommissioning node is +recommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_restart` + +An event of type `node_restart` is recorded when an existing node rejoins the cluster +after being offline. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_connection_timeout` + +An event of type `node_shutdown_connection_timeout` is recorded when SQL connections remain open +during shutdown, after waiting for the server.shutdown.connections.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still open after waiting for the client to close them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.connections.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_transaction_timeout` + +An event of type `node_shutdown_transaction_timeout` is recorded when SQL transactions remain open +during shutdown, after waiting for the server.shutdown.transactions.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still running SQL transactions after waiting for the client to end them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.transactions.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `tenant_shared_service_start` + +An event of type `tenant_shared_service_start` is recorded when a tenant server +is started inside the same process as the KV layer. + + +| Field | Description | Sensitive | +|--|--|--| +| `OK` | Whether the startup was successful. | no | +| `ErrorText` | If the startup failed, the text of the error. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +### `tenant_shared_service_stop` + +An event of type `tenant_shared_service_stop` is recorded when a tenant server +is shut down inside the same process as the KV layer. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +## Debugging events + +Events in this category pertain to debugging operations performed by +operators or (more commonly) Cockroach Labs employees. These operations can +e.g. directly access and mutate internal state, breaking system invariants. + +Events in this category are logged to the `OPS` channel. + + +### `debug_recover_replica` + +An event of type `debug_recover_replica` is recorded when unsafe loss of quorum recovery is performed. + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `StoreID` | | no | +| `SurvivorReplicaID` | | no | +| `UpdatedReplicaID` | | no | +| `StartKey` | | yes | +| `EndKey` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +### `debug_send_kv_batch` + +An event of type `debug_send_kv_batch` is recorded when an arbitrary KV BatchRequest is submitted +to the cluster via the `debug send-kv-batch` CLI command. + + +| Field | Description | Sensitive | +|--|--|--| +| `BatchRequest` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +## Health events + +Events in this category pertain to the health of one or more servers. + +Events in this category are logged to the `HEALTH` channel. + + +### `runtime_stats` + +An event of type `runtime_stats` is recorded every 10 seconds as server health metrics. + + +| Field | Description | Sensitive | +|--|--|--| +| `MemRSSBytes` | The process resident set size. Expressed as bytes. | no | +| `GoroutineCount` | The number of goroutines. | no | +| `MemStackSysBytes` | The stack system memory used. Expressed as bytes. | no | +| `GoAllocBytes` | The memory allocated by Go. Expressed as bytes. | no | +| `GoTotalBytes` | The total memory allocated by Go but not released. Expressed as bytes. | no | +| `GoStatsStaleness` | The staleness of the Go memory statistics. Expressed in seconds. | no | +| `HeapFragmentBytes` | The amount of heap fragmentation. Expressed as bytes. | no | +| `HeapReservedBytes` | The amount of heap reserved. Expressed as bytes. | no | +| `HeapReleasedBytes` | The amount of heap released. Expressed as bytes. | no | +| `CGoAllocBytes` | The memory allocated outside of Go. Expressed as bytes. | no | +| `CGoTotalBytes` | The total memory allocated outside of Go but not released. Expressed as bytes. | no | +| `CGoCallRate` | The total number of calls outside of Go over time. Expressed as operations per second. | no | +| `CPUUserPercent` | The user CPU percentage. | no | +| `CPUSysPercent` | The system CPU percentage. | no | +| `GCPausePercent` | The GC pause percentage. | no | +| `GCRunCount` | The total number of GC runs. | no | +| `NetHostRecvBytes` | The bytes received on all network interfaces since this process started. | no | +| `NetHostSendBytes` | The bytes sent on all network interfaces since this process started. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Job events + +Events in this category pertain to long-running jobs that are orchestrated by +a node's job registry. These system processes can create and/or modify stored +objects during the course of their execution. + +A job might choose to emit multiple events during its execution when +transitioning from one "state" to another. +Egs: IMPORT/RESTORE will emit events on job creation and successful +completion. If the job fails, events will be emitted on job creation, +failure, and successful revert. + +Events in this category are logged to the `OPS` channel. + + +### `import` + +An event of type `import` is recorded when an import job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `restore` + +An event of type `restore` is recorded when a restore job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `status_change` + +An event of type `status_change` is recorded when a job changes statuses. + + +| Field | Description | Sensitive | +|--|--|--| +| `JobID` | The ID of the job that is changing statuses. | no | +| `JobType` | The type of the job that is changing statuses. | no | +| `Description` | A human parsable description of the status change | partially | +| `PreviousStatus` | The status that the job is transitioning out of | no | +| `NewStatus` | The status that the job has transitioned into | no | +| `RunNum` | The run number of the job. | no | +| `Error` | An error that may have occurred while the job was running. | yes | +| `FinalResumeErr` | An error that occurred that requires the job to be reverted. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Miscellaneous SQL events + +Events in this category report miscellaneous SQL events. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own system.eventlog table. + +Events in this category are logged to the `OPS` channel. + + +### `set_cluster_setting` + +An event of type `set_cluster_setting` is recorded when a cluster setting is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `set_tenant_cluster_setting` + +An event of type `set_tenant_cluster_setting` is recorded when a cluster setting override +is changed, either for another tenant or for all tenants. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | +| `TenantId` | The target Tenant ID. Empty if targeting all tenants. | no | +| `AllTenants` | Whether the override applies to all tenants. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +## SQL Access Audit Events + +Events in this category are generated when a table has been +marked as audited via `ALTER TABLE ... EXPERIMENTAL_AUDIT SET`. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SENSITIVE_ACCESS` channel. + + +### `admin_query` + +An event of type `admin_query` is recorded when a user with admin privileges (the user +is directly or indirectly a member of the admin role) executes a query. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `role_based_audit_event` + +An event of type `role_based_audit_event` is an audit event recorded when an executed query belongs to a user whose role +membership(s) correspond to any role that is enabled to emit an audit log via the sql.log.user_audit +cluster setting. + + +| Field | Description | Sensitive | +|--|--|--| +| `Role` | The configured audit role that emitted this log. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sensitive_table_access` + +An event of type `sensitive_table_access` is recorded when an access is performed to +a table marked as audited. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table being audited. | yes | +| `AccessMode` | How the table was accessed (r=read / rw=read/write). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +## SQL Execution Log + +Events in this category report executed queries. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `query_execute` + +An event of type `query_execute` is recorded when a query is executed, +and the cluster setting `sql.log.all_statements.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +## SQL Logical Schema Changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the SQL logical +schema. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SQL_SCHEMA` channel. + + +### `alter_database_add_region` + +An event of type `alter_database_add_region` is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `RegionName` | The region being added. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_drop_region` + +AlterDatabaseAddRegion is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `RegionName` | The region being dropped. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_placement` + +An event of type `alter_database_placement` is recorded when the database placement is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `Placement` | The new placement policy. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_primary_region` + +An event of type `alter_database_primary_region` is recorded when a primary region is added/modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `PrimaryRegionName` | The new primary region. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_set_zone_config_extension` + +An event of type `alter_database_set_zone_config_extension` is recorded when a zone config extension is changed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `alter_database_survival_goal` + +An event of type `alter_database_survival_goal` is recorded when the survival goal is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `SurvivalGoal` | The new survival goal | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_function_options` + +An event of type `alter_function_options` is recorded when a user-defined function's options are +altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the affected function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_index` + +An event of type `alter_index` is recorded when an index is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_index_visible` + +AlterIndex is recorded when an index visibility is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `NotVisible` | Set true if index is not visible. NOTE: THIS FIELD IS DEPRECATED in favor of invisibility. | no | +| `Invisibility` | The new invisibility of the affected index. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_sequence` + +An event of type `alter_sequence` is recorded when a sequence is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_table` + +An event of type `alter_table` is recorded when a table is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update, if any. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_type` + +EventAlterType is recorded when a user-defined type is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_column` + +An event of type `comment_on_column` is recorded when a column is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected column. | no | +| `ColumnName` | The affected column. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_constraint` + +An event of type `comment_on_constraint` is recorded when an constraint is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected constraint. | no | +| `ConstraintName` | The name of the affected constraint. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_database` + +CommentOnTable is recorded when a database is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_index` + +An event of type `comment_on_index` is recorded when an index is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_schema` + + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | Name of the affected schema. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_table` + +An event of type `comment_on_table` is recorded when a table is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_type` + +An event of type `comment_on_type` is recorded when a type is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_database` + +An event of type `create_database` is recorded when a database is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the new database. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_function` + +An event of type `create_function` is recorded when a user-defined function is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the created function. | no | +| `IsReplace` | If the new function is a replace of an existing function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_index` + +An event of type `create_index` is recorded when an index is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the new index. | no | +| `IndexName` | The name of the new index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_schema` + +An event of type `create_schema` is recorded when a schema is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the new schema. | no | +| `Owner` | The name of the owner for the new schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_sequence` + +An event of type `create_sequence` is recorded when a sequence is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the new sequence. | no | +| `Owner` | The name of the owner for the new sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_statistics` + +An event of type `create_statistics` is recorded when statistics are collected for a +table. + +Events of this type are only collected when the cluster setting +`sql.stats.post_events.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table for which the statistics were created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_table` + +An event of type `create_table` is recorded when a table is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the new table. | no | +| `Owner` | The name of the owner for the new table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_trigger` + +An event of type `create_trigger` is recorded when a trigger is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the trigger's table. | no | +| `TriggerName` | Name of the created trigger. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_type` + +An event of type `create_type` is recorded when a user-defined type is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the new type. | no | +| `Owner` | The name of the owner for the new type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_view` + +An event of type `create_view` is recorded when a view is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the new view. | no | +| `Owner` | The name of the owner of the new view. | no | +| `ViewQuery` | The SQL selection clause used to define the view. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_database` + +An event of type `drop_database` is recorded when a database is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | no | +| `DroppedSchemaObjects` | The names of the schemas dropped by a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_function` + +An event of type `drop_function` is recorded when a user-defined function is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the dropped function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_index` + +An event of type `drop_index` is recorded when an index is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_schema` + +An event of type `drop_schema` is recorded when a schema is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_sequence` + +An event of type `drop_sequence` is recorded when a sequence is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_table` + +An event of type `drop_table` is recorded when a table is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_trigger` + +An event of type `drop_trigger` is recorded when a trigger is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the trigger's table. | no | +| `TriggerName` | Name of the dropped trigger. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_type` + +An event of type `drop_type` is recorded when a user-defined type is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_view` + +An event of type `drop_view` is recorded when a view is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the affected view. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `finish_schema_change` + +An event of type `finish_schema_change` is recorded when a previously initiated schema +change has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to complete. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `finish_schema_change_rollback` + +An event of type `finish_schema_change_rollback` is recorded when a previously +initiated schema change rollback has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to rollback. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `force_delete_table_data_entry` + + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_database` + +An event of type `rename_database` is recorded when a database is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The old name of the affected database. | no | +| `NewDatabaseName` | The new name of the affected database. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_function` + +An event of type `rename_function` is recorded when a user-defined function is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The old name of the affected function. | no | +| `NewFunctionName` | The new name of the affected function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_schema` + +An event of type `rename_schema` is recorded when a schema is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The old name of the affected schema. | no | +| `NewSchemaName` | The new name of the affected schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_table` + +An event of type `rename_table` is recorded when a table, sequence or view is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The old name of the affected table. | no | +| `NewTableName` | The new name of the affected table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_type` + +An event of type `rename_type` is recorded when a user-defined type is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The old name of the affected type. | no | +| `NewTypeName` | The new name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `reverse_schema_change` + +An event of type `reverse_schema_change` is recorded when an in-progress schema change +encounters a problem and is reversed. + + +| Field | Description | Sensitive | +|--|--|--| +| `Error` | The error encountered that caused the schema change to be reversed. The specific format of the error is variable and can change across releases without warning. | partially | +| `SQLSTATE` | The SQLSTATE code for the error. | no | +| `LatencyNanos` | The amount of time the schema change job took before being reverted. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `set_schema` + +An event of type `set_schema` is recorded when a table, view, sequence or type's schema is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorName` | The old name of the affected descriptor. | no | +| `NewDescriptorName` | The new name of the affected descriptor. | no | +| `DescriptorType` | The descriptor type being changed (table, view, sequence, type). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `truncate_table` + +An event of type `truncate_table` is recorded when a table is truncated. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_delete_descriptor` + +An event of type `unsafe_delete_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_delete_descriptor(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_delete_namespace_entry` + +An event of type `unsafe_delete_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_delete_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_upsert_descriptor` + +An event of type `unsafe_upsert_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_upsert_descriptor(). + + +| Field | Description | Sensitive | +|--|--|--| +| `PreviousDescriptor` | | yes | +| `NewDescriptor` | | yes | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_upsert_namespace_entry` + +An event of type `unsafe_upsert_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_upsert_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `PreviousID` | | no | +| `Force` | | no | +| `FailedValidation` | | no | +| `ValidationErrors` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +## SQL Privilege changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the privilege +grants for stored objects. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `PRIVILEGES` channel. + + +### `alter_database_owner` + +An event of type `alter_database_owner` is recorded when a database's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database being affected. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_default_privileges` + +An event of type `alter_default_privileges` is recorded when default privileges are changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | +| `RoleName` | Either role_name should be populated or for_all_roles should be true. The role having its default privileges altered. | yes | +| `ForAllRoles` | Identifies if FOR ALL ROLES is used. | no | +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `alter_function_owner` + +AlterTableOwner is recorded when the owner of a user-defined function is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The name of the affected user-defined function. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_schema_owner` + +An event of type `alter_schema_owner` is recorded when a schema's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_table_owner` + +An event of type `alter_table_owner` is recorded when the owner of a table, view or sequence is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected object. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_type_owner` + +An event of type `alter_type_owner` is recorded when the owner of a user-defiend type is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `change_database_privilege` + +An event of type `change_database_privilege` is recorded when privileges are +added to / removed from a user for a database object. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_function_privilege` + + + +| Field | Description | Sensitive | +|--|--|--| +| `FuncName` | The name of the affected function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_schema_privilege` + +An event of type `change_schema_privilege` is recorded when privileges are added to / +removed from a user for a schema object. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_table_privilege` + +An event of type `change_table_privilege` is recorded when privileges are added to / removed +from a user for a table, sequence or view object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_type_privilege` + +An event of type `change_type_privilege` is recorded when privileges are added to / +removed from a user for a type object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +## SQL Session events + +Events in this category report SQL client connections +and sessions. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SESSIONS` channel. + + +### `client_authentication_failed` + +An event of type `client_authentication_failed` is reported when a client session +did not authenticate successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Reason` | The reason for the authentication failure. See below for possible values for type `AuthFailReason`. | no | +| `Detail` | The detailed error for the authentication failure. | partially | +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_info` + +An event of type `client_authentication_info` is reported for intermediate +steps during the authentication process. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used, once known. | no | +| `Info` | The authentication progress message. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_ok` + +An event of type `client_authentication_ok` is reported when a client session +was authenticated successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_connection_end` + +An event of type `client_connection_end` is reported when a client connection +is closed. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_connection_start` + +An event of type `client_connection_start` is reported when a client connection +is established. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_session_end` + +An event of type `client_session_end` is reported when a client session +is completed. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +## SQL Slow Query Log + +Events in this category report slow query execution. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_PERF` channel. + + +### `large_row` + +An event of type `large_row` is recorded when a statement tries to write a row larger than +cluster setting `sql.guardrails.max_row_size_log` to the database. Multiple +LargeRow events will be recorded for statements writing multiple large rows. +LargeRow events are recorded before the transaction commits, so in the case +of transaction abort there will not be a corresponding row in the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query` + +An event of type `slow_query` is recorded when a query triggers the "slow query" condition. + +As of this writing, the condition requires: +- the cluster setting `sql.log.slow_query.latency_threshold` +set to a non-zero value, AND +- EITHER of the following conditions: +- the actual age of the query exceeds the configured threshold; AND/OR +- the query performs a full table/index scan AND the cluster setting +`sql.log.slow_query.experimental_full_table_scans.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit` + +An event of type `txn_rows_read_limit` is recorded when a transaction tries to read more rows than +cluster setting `sql.defaults.transaction_rows_read_log`. There will only be +a single record for a single transaction (unless it is retried) even if there +are more statement within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit` + +An event of type `txn_rows_written_limit` is recorded when a transaction tries to write more rows +than cluster setting `sql.defaults.transaction_rows_written_log`. There will +only be a single record for a single transaction (unless it is retried) even +if there are more mutation statements within the transaction that haven't +been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL Slow Query Log (Internal) + +Events in this category report slow query execution by +internal executors, i.e., when CockroachDB internally issues +SQL statements. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_INTERNAL_PERF` channel. + + +### `large_row_internal` + +An event of type `large_row_internal` is recorded when an internal query tries to write a row +larger than cluster settings `sql.guardrails.max_row_size_log` or +`sql.guardrails.max_row_size_err` to the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query_internal` + +An event of type `slow_query_internal` is recorded when a query triggers the "slow query" condition, +and the cluster setting `sql.log.slow_query.internal_queries.enabled` is +set. +See the documentation for the event type `slow_query` for details about +the "slow query" condition. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit_internal` + +An event of type `txn_rows_read_limit_internal` is recorded when an internal transaction tries to +read more rows than cluster setting `sql.defaults.transaction_rows_read_log` +or `sql.defaults.transaction_rows_read_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit_internal` + +An event of type `txn_rows_written_limit_internal` is recorded when an internal transaction tries to +write more rows than cluster setting +`sql.defaults.transaction_rows_written_log` or +`sql.defaults.transaction_rows_written_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL User and Role operations + +Events in this category pertain to SQL statements that modify the +properties of users and roles. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `USER_ADMIN` channel. + + +### `alter_role` + +An event of type `alter_role` is recorded when a role is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | +| `Options` | The options set on the user/role. | no | +| `SetInfo` | Information corresponding to an ALTER ROLE SET statement. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_role` + +An event of type `create_role` is recorded when a role is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the new user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_role` + +An event of type `drop_role` is recorded when a role is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `grant_role` + +An event of type `grant_role` is recorded when a role is granted. + + +| Field | Description | Sensitive | +|--|--|--| +| `GranteeRoles` | The roles being granted to. | yes | +| `Members` | The roles being granted. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `password_hash_converted` + +An event of type `password_hash_converted` is recorded when the password credentials +are automatically converted server-side. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the user/role whose credentials have been converted. | yes | +| `OldMethod` | The previous hash method. | no | +| `NewMethod` | The new hash method. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Storage telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `level_stats` + +An event of type `level_stats` contains per-level statistics for an LSM. + + +| Field | Description | Sensitive | +|--|--|--| +| `Level` | level is the level ID in a LSM (e.g. level(L0) == 0, etc.) | no | +| `NumFiles` | num_files is the number of files in the level (gauge). | no | +| `SizeBytes` | size_bytes is the size of the level, in bytes (gauge). | no | +| `Score` | score is the compaction score of the level (gauge). | no | +| `BytesIn` | bytes_in is the number of bytes written to this level (counter). | no | +| `BytesIngested` | bytes_ingested is the number of bytes ingested into this level (counter). | no | +| `BytesMoved` | bytes_moved is the number of bytes moved into this level via a move-compaction (counter). | no | +| `BytesRead` | bytes_read is the number of bytes read from this level, during compactions (counter). | no | +| `BytesCompacted` | bytes_compacted is the number of bytes written to this level during compactions (counter). | no | +| `BytesFlushed` | bytes flushed is the number of bytes flushed to this level. This value is always zero for levels other than L0 (counter). | no | +| `TablesCompacted` | tables_compacted is the count of tables compacted into this level (counter). | no | +| `TablesFlushed` | tables_flushed is the count of tables flushed into this level (counter). | no | +| `TablesIngested` | tables_ingested is the count of tables ingested into this level (counter). | no | +| `TablesMoved` | tables_moved is the count of tables moved into this level via move-compactions (counter). | no | +| `NumSublevels` | num_sublevel is the count of sublevels for the level. This value is always zero for levels other than L0 (gauge). | no | + + + +### `store_stats` + +An event of type `store_stats` contains per store stats. + +Note that because stats are scoped to the lifetime of the process, counters +(and certain gauges) will be reset across node restarts. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeId` | node_id is the ID of the node. | no | +| `StoreId` | store_id is the ID of the store. | no | +| `Levels` | levels is a nested message containing per-level statistics. | yes | +| `CacheSize` | cache_size is the size of the cache for the store, in bytes (gauge). | no | +| `CacheCount` | cache_count is the number of items in the cache (gauge). | no | +| `CacheHits` | cache_hits is the number of cache hits (counter). | no | +| `CacheMisses` | cache_misses is the number of cache misses (counter). | no | +| `CompactionCountDefault` | compaction_count_default is the count of default compactions (counter). | no | +| `CompactionCountDeleteOnly` | compaction_count_delete_only is the count of delete-only compactions (counter). | no | +| `CompactionCountElisionOnly` | compaction_count_elision_only is the count of elision-only compactions (counter). | no | +| `CompactionCountMove` | compaction_count_move is the count of move-compactions (counter). | no | +| `CompactionCountRead` | compaction_count_read is the count of read-compactions (counter). | no | +| `CompactionCountRewrite` | compaction_count_rewrite is the count of rewrite-compactions (counter). | no | +| `CompactionNumInProgress` | compactions_num_in_progress is the number of compactions in progress (gauge). | no | +| `CompactionMarkedFiles` | compaction_marked_files is the count of files marked for compaction (gauge). | no | +| `FlushCount` | flush_count is the number of flushes (counter). | no | +| `FlushIngestCount` | | no | +| `FlushIngestTableCount` | | no | +| `FlushIngestTableBytes` | | no | +| `IngestCount` | ingest_count is the number of successful ingest operations (counter). | no | +| `MemtableSize` | memtable_size is the total size allocated to all memtables and (large) batches, in bytes (gauge). | no | +| `MemtableCount` | memtable_count is the count of memtables (gauge). | no | +| `MemtableZombieCount` | memtable_zombie_count is the count of memtables no longer referenced by the current DB state, but still in use by an iterator (gauge). | no | +| `MemtableZombieSize` | memtable_zombie_size is the size, in bytes, of all zombie memtables (gauge). | no | +| `WalLiveCount` | wal_live_count is the count of live WAL files (gauge). | no | +| `WalLiveSize` | wal_live_size is the size, in bytes, of live data in WAL files. With WAL recycling, this value is less than the actual on-disk size of the WAL files (gauge). | no | +| `WalObsoleteCount` | wal_obsolete_count is the count of obsolete WAL files (gauge). | no | +| `WalObsoleteSize` | wal_obsolete_size is the size of obsolete WAL files, in bytes (gauge). | no | +| `WalPhysicalSize` | wal_physical_size is the size, in bytes, of the WAL files on disk (gauge). | no | +| `WalBytesIn` | wal_bytes_in is the number of logical bytes written to the WAL (counter). | no | +| `WalBytesWritten` | wal_bytes_written is the number of bytes written to the WAL (counter). | no | +| `TableObsoleteCount` | table_obsolete_count is the number of tables which are no longer referenced by the current DB state or any open iterators (gauge). | no | +| `TableObsoleteSize` | table_obsolete_size is the size, in bytes, of obsolete tables (gauge). | no | +| `TableZombieCount` | table_zombie_count is the number of tables no longer referenced by the current DB state, but are still in use by an open iterator (gauge). | no | +| `TableZombieSize` | table_zombie_size is the size, in bytes, of zombie tables (gauge). | no | +| `RangeKeySetsCount` | range_key_sets_count is the approximate count of internal range key sets in the store. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `captured_index_usage_stats` + +An event of type `captured_index_usage_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `TotalReadCount` | TotalReadCount is the number of times the index has been read. | no | +| `LastRead` | LastRead is the timestamp at which the index was last read. | no | +| `TableID` | TableID is the ID of the table on which the index was created. This is same as descpb.TableID and is unique within the cluster. | no | +| `IndexID` | IndexID is the ID of the index within the scope of the given table. | no | +| `DatabaseName` | DatabaseName is the name of the database in which the index was created. | no | +| `TableName` | TableName is the name of the table on which the index was created. | no | +| `IndexName` | IndexName is the name of the index within the scope of the given table. | no | +| `IndexType` | IndexType is the type of the index. Index types include "primary" and "secondary". | no | +| `IsUnique` | IsUnique indicates if the index has a UNIQUE constraint. | no | +| `IsInverted` | IsInverted indicates if the index is an inverted index. | no | +| `CreatedAt` | CreatedAt is the timestamp at which the index was created. | no | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `hot_ranges_stats` + +An event of type `hot_ranges_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `Qps` | | no | +| `DatabaseName` | DatabaseName is the name of the database in which the index was created. | yes | +| `TableName` | TableName is the name of the table on which the index was created. | yes | +| `IndexName` | IndexName is the name of the index within the scope of the given table. | yes | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | yes | +| `LeaseholderNodeID` | LeaseholderNodeID indicates the Node ID that is the current leaseholder for the given range. | no | +| `WritesPerSecond` | Writes per second is the recent number of keys written per second on this range. | no | +| `ReadsPerSecond` | Reads per second is the recent number of keys read per second on this range. | no | +| `WriteBytesPerSecond` | Write bytes per second is the recent number of bytes written per second on this range. | no | +| `ReadBytesPerSecond` | Read bytes per second is the recent number of bytes read per second on this range. | no | +| `CPUTimePerSecond` | CPU time per second is the recent cpu usage in nanoseconds of this range. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `m_v_c_c_iterator_stats` + +Internal storage iteration statistics for a single execution. + + +| Field | Description | Sensitive | +|--|--|--| +| `StepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `StepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `BlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `BlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `KeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `ValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | + + + +### `recovery_event` + +An event of type `recovery_event` is an event that is logged on every invocation of BACKUP, +RESTORE, and on every BACKUP schedule creation, with the appropriate subset +of fields populated depending on the type of event. This event is is also +logged whenever a BACKUP and RESTORE job completes or fails. + + +| Field | Description | Sensitive | +|--|--|--| +| `RecoveryType` | RecoveryType is the type of recovery described by this event, which is one of - backup - scheduled_backup - create_schedule - restore

It can also be a job event corresponding to the recovery, which is one of - backup_job - scheduled_backup_job - restore_job | no | +| `TargetScope` | TargetScope is the largest scope of the targets that the user is backing up or restoring based on the following order: table < schema < database < full cluster. | no | +| `IsMultiregionTarget` | IsMultiregionTarget is true if any of the targets contain objects with multi-region primitives. | no | +| `TargetCount` | TargetCount is the number of targets the in the BACKUP/RESTORE. | no | +| `DestinationSubdirType` | DestinationSubdirType is - latest: if using the latest subdir - standard: if using a date-based subdir - custom: if using a custom subdir that's not date-based | no | +| `DestinationStorageTypes` | DestinationStorageTypes are the types of storage that the user is backing up to or restoring from. | no | +| `DestinationAuthTypes` | DestinationAuthTypes are the types of authentication methods that the user is using to access the destination storage. | no | +| `IsLocalityAware` | IsLocalityAware indicates if the BACKUP or RESTORE is locality aware. | no | +| `AsOfInterval` | AsOfInterval is the time interval in nanoseconds between the statement timestamp and the timestamp resolved by the AS OF SYSTEM TIME expression. The interval is expressed in nanoseconds. | no | +| `WithRevisionHistory` | WithRevisionHistory is true if the BACKUP includes revision history. | no | +| `HasEncryptionPassphrase` | HasEncryptionPassphrase is true if the user provided an encryption passphrase to encrypt/decrypt their backup. | no | +| `KMSType` | KMSType is the type of KMS the user is using to encrypt/decrypt their backup. | no | +| `KMSCount` | KMSCount is the number of KMS the user is using. | no | +| `Options` | Options contain all the names of the options specified by the user in the BACKUP or RESTORE statement. For options that are accompanied by a value, only those with non-empty values will be present.

It's important to note that there are no option values anywhere in the event payload. Future changes to telemetry should refrain from adding values to the payload unless they are properly redacted. | no | +| `DebugPauseOn` | DebugPauseOn is the type of event that the restore should pause on for debugging purposes. Currently only "error" is supported. | no | +| `JobID` | JobID is the ID of the BACKUP/RESTORE job. | no | +| `ResultStatus` | ResultStatus indicates whether the job succeeded or failed. | no | +| `ErrorText` | ErrorText is the text of the error that caused the job to fail. | partially | +| `RecurringCron` | RecurringCron is the crontab for the incremental backup. | no | +| `FullBackupCron` | FullBackupCron is the crontab for the full backup. | no | +| `CustomFirstRunTime` | CustomFirstRunTime is the timestamp for the user configured first run time. Expressed as nanoseconds since the Unix epoch. | no | +| `OnExecutionFailure` | OnExecutionFailure describes the desired behavior if the schedule fails to execute. | no | +| `OnPreviousRunning` | OnPreviousRunning describes the desired behavior if the previously scheduled BACKUP is still running. | no | +| `IgnoreExistingBackup` | IgnoreExistingBackup is true iff the BACKUP schedule should still be created even if a backup is already present in its destination. | no | +| `ApplicationName` | The application name for the session where recovery event was created. | no | +| `NumRows` | NumRows is the number of rows successfully imported, backed up or restored. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `sampled_exec_stats` + +An event of type `sampled_exec_stats` contains execution statistics that apply to both statements +and transactions. These stats as a whole are collected using a sampling approach. +These exec stats are meant to contain the same fields as ExecStats in +apps_stats.proto but are for a single execution rather than aggregated executions. +Fields in this struct should be updated in sync with apps_stats.proto. + + +| Field | Description | Sensitive | +|--|--|--| +| `NetworkBytes` | NetworkBytes collects the number of bytes sent over the network. | no | +| `MaxMemUsage` | MaxMemUsage collects the maximum memory usage that occurred on a node. | no | +| `ContentionTime` | ContentionTime collects the time in seconds statements in the transaction spent contending. | no | +| `NetworkMessages` | NetworkMessages collects the number of messages that were sent over the network. | no | +| `MaxDiskUsage` | MaxDiskUsage collects the maximum temporary disk usage that occurred. This is set in cases where a query had to spill to disk, e.g. when performing a large sort where not all of the tuples fit in memory. | no | +| `CPUSQLNanos` | CPUSQLNanos collects the CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `MVCCIteratorStats` | Internal storage iteration statistics. | yes | + + + +### `sampled_query` + +An event of type `sampled_query` is the SQL query event logged to the telemetry channel. It +contains common SQL event/execution details. + + +| Field | Description | Sensitive | +|--|--|--| +| `SkippedQueries` | skipped_queries indicate how many SQL statements were not considered for sampling prior to this one. If the field is omitted, or its value is zero, this indicates that no statement was omitted since the last event. | no | +| `CostEstimate` | Cost of the query as estimated by the optimizer. | no | +| `Distribution` | The distribution of the DistSQL query plan (local, full, or partial). | no | +| `PlanGist` | The query's plan gist bytes as a base64 encoded string. | no | +| `SessionID` | SessionID is the ID of the session that initiated the query. | no | +| `Database` | Name of the database that initiated the query. | no | +| `StatementID` | Statement ID of the query. | no | +| `TransactionID` | Transaction ID of the query. | no | +| `MaxFullScanRowsEstimate` | Maximum number of rows scanned by a full scan, as estimated by the optimizer. | no | +| `TotalScanRowsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer. | no | +| `OutputRowsEstimate` | The number of rows output by the query, as estimated by the optimizer. | no | +| `StatsAvailable` | Whether table statistics were available to the optimizer when planning the query. | no | +| `NanosSinceStatsCollected` | The maximum number of nanoseconds that have passed since stats were collected on any table scanned by this query. | no | +| `BytesRead` | The number of bytes read from disk. | no | +| `RowsRead` | The number of rows read from disk. | no | +| `RowsWritten` | The number of rows written. | no | +| `InnerJoinCount` | The number of inner joins in the query plan. | no | +| `LeftOuterJoinCount` | The number of left (or right) outer joins in the query plan. | no | +| `FullOuterJoinCount` | The number of full outer joins in the query plan. | no | +| `SemiJoinCount` | The number of semi joins in the query plan. | no | +| `AntiJoinCount` | The number of anti joins in the query plan. | no | +| `IntersectAllJoinCount` | The number of intersect all joins in the query plan. | no | +| `ExceptAllJoinCount` | The number of except all joins in the query plan. | no | +| `HashJoinCount` | The number of hash joins in the query plan. | no | +| `CrossJoinCount` | The number of cross joins in the query plan. | no | +| `IndexJoinCount` | The number of index joins in the query plan. | no | +| `LookupJoinCount` | The number of lookup joins in the query plan. | no | +| `MergeJoinCount` | The number of merge joins in the query plan. | no | +| `InvertedJoinCount` | The number of inverted joins in the query plan. | no | +| `ApplyJoinCount` | The number of apply joins in the query plan. | no | +| `ZigZagJoinCount` | The number of zig zag joins in the query plan. | no | +| `ContentionNanos` | The duration of time in nanoseconds that the query experienced contention. | no | +| `Regions` | The regions of the nodes where SQL processors ran. | no | +| `NetworkBytesSent` | The number of network bytes sent by nodes for this query. | no | +| `MaxMemUsage` | The maximum amount of memory usage by nodes for this query. | no | +| `MaxDiskUsage` | The maximum amount of disk usage by nodes for this query. | no | +| `KVBytesRead` | The number of bytes read at the KV layer for this query. | no | +| `KVPairsRead` | The number of key-value pairs read at the KV layer for this query. | no | +| `KVRowsRead` | The number of rows read at the KV layer for this query. | no | +| `NetworkMessages` | The number of network messages sent by nodes for this query. | no | +| `IndexRecommendations` | Generated index recommendations for this query. | no | +| `ScanCount` | The number of scans in the query plan. | no | +| `ScanWithStatsCount` | The number of scans using statistics (including forecasted statistics) in the query plan. | no | +| `ScanWithStatsForecastCount` | The number of scans using forecasted statistics in the query plan. | no | +| `TotalScanRowsWithoutForecastsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer without using forecasts. | no | +| `NanosSinceStatsForecasted` | The greatest quantity of nanoseconds that have passed since the forecast time (or until the forecast time, if it is in the future, in which case it will be negative) for any table with forecasted stats scanned by this query. | no | +| `Indexes` | The list of indexes used by this query. | no | +| `CpuTimeNanos` | Collects the cumulative CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `KvGrpcCalls` | The number of grpc calls done to get data form KV nodes | no | +| `KvTimeNanos` | Cumulated time spent waiting for a KV request. This includes disk IO time and potentially network time (if any of the keys are not local). | no | +| `ServiceLatencyNanos` | The time to service the query, from start of parse to end of execute. | no | +| `OverheadLatencyNanos` | The difference between service latency and the sum of parse latency + plan latency + run latency . | no | +| `RunLatencyNanos` | The time to run the query and fetch or compute the result rows. | no | +| `PlanLatencyNanos` | The time to transform the AST into a logical query plan. | no | +| `IdleLatencyNanos` | The time between statement executions in a transaction | no | +| `ParseLatencyNanos` | The time to transform the SQL string into an abstract syntax tree (AST). | no | +| `MvccStepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccStepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccBlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `MvccBlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `MvccKeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `SchemaChangerMode` | SchemaChangerMode is the mode that was used to execute the schema change, if any. | no | +| `SQLInstanceIDs` | SQLInstanceIDs is a list of all the SQL instances used in this statement's execution. | no | +| `KVNodeIDs` | KVNodeIDs is a list of all the KV nodes used in this statement's execution. | no | +| `StatementFingerprintID` | Statement fingerprint ID of the query. | no | +| `UsedFollowerRead` | UsedFollowerRead indicates whether at least some reads were served by the follower replicas. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sampled_transaction` + +An event of type `sampled_transaction` is the event logged to telemetry at the end of transaction execution. + + +| Field | Description | Sensitive | +|--|--|--| +| `User` | User is the user account that triggered the transaction. The special usernames `root` and `node` are not considered sensitive. | depends | +| `ApplicationName` | ApplicationName is the application name for the session where the transaction was executed. This is included in the event to ease filtering of logging output by application. | no | +| `TxnCounter` | TxnCounter is the sequence number of the SQL transaction inside its session. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `TransactionID` | TransactionID is the id of the transaction. | no | +| `Committed` | Committed indicates if the transaction committed successfully. We want to include this value even if it is false. | no | +| `ImplicitTxn` | ImplicitTxn indicates if the transaction was an implicit one. We want to include this value even if it is false. | no | +| `StartTimeUnixNanos` | StartTimeUnixNanos is the time the transaction was started. Expressed as unix time in nanoseconds. | no | +| `EndTimeUnixNanos` | EndTimeUnixNanos the time the transaction finished (either committed or aborted). Expressed as unix time in nanoseconds. | no | +| `ServiceLatNanos` | ServiceLatNanos is the time to service the whole transaction, from start to end of execution. | no | +| `SQLSTATE` | SQLSTATE is the SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | ErrorText is the text of the error if any. | partially | +| `NumRetries` | NumRetries is the number of time when the txn was retried automatically by the server. | no | +| `LastAutoRetryReason` | LastAutoRetryReason is a string containing the reason for the last automatic retry. | partially | +| `NumRows` | NumRows is the total number of rows returned across all statements. | no | +| `RetryLatNanos` | RetryLatNanos is the amount of time spent retrying the transaction. | no | +| `CommitLatNanos` | CommitLatNanos is the amount of time spent committing the transaction after all statement operations. | no | +| `IdleLatNanos` | IdleLatNanos is the amount of time spent waiting for the client to send statements while the transaction is open. | no | +| `BytesRead` | BytesRead is the number of bytes read from disk. | no | +| `RowsRead` | RowsRead is the number of rows read from disk. | no | +| `RowsWritten` | RowsWritten is the number of rows written to disk. | no | +| `SampledExecStats` | SampledExecStats is a nested field containing execution statistics. This field will be omitted if the stats were not sampled. | yes | +| `SkippedTransactions` | SkippedTransactions is the number of transactions that were skipped as part of sampling prior to this one. We only count skipped transactions when telemetry logging is enabled and the sampling mode is set to "transaction". | no | +| `TransactionFingerprintID` | TransactionFingerprintID is the fingerprint ID of the transaction. This can be used to find the transaction in the console. | no | +| `StatementFingerprintIDs` | StatementFingerprintIDs is an array of statement fingerprint IDs belonging to this transaction. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_descriptor` + +An event of type `schema_descriptor` is an event for schema telemetry, whose purpose is +to take periodic snapshots of the cluster's SQL schema and publish them in +the telemetry log channel. For all intents and purposes, the data in such a +snapshot can be thought of the outer join of certain system tables: +namespace, descriptor, and at some point perhaps zones, etc. + +Snapshots are too large to conveniently be published as a single log event, +so instead they're broken down into SchemaDescriptor events which +contain the data in one record of this outer join projection. These events +are prefixed by a header (a SchemaSnapshotMetadata event). + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of the snapshot that this event is part of. | no | +| `ParentDatabaseID` | ParentDatabaseID matches the same key column in system.namespace. | no | +| `ParentSchemaID` | ParentSchemaID matches the same key column in system.namespace. | no | +| `Name` | Name matches the same key column in system.namespace. | no | +| `DescID` | DescID matches the 'id' column in system.namespace and system.descriptor. | no | +| `Desc` | Desc matches the 'descriptor' column in system.descriptor. Some contents of the descriptor may be redacted to prevent leaking PII. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_snapshot_metadata` + +An event of type `schema_snapshot_metadata` is an event describing a schema snapshot, which +is a set of SchemaDescriptor messages sharing the same SnapshotID. + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of this snapshot. | no | +| `NumRecords` | NumRecords is how many SchemaDescriptor events are in the snapshot. | no | +| `AsOfTimestamp` | AsOfTimestamp is when the snapshot was taken. This is equivalent to the timestamp given in the AS OF SYSTEM TIME clause when querying the namespace and descriptor tables in the system database. Expressed as nanoseconds since the Unix epoch. | no | +| `Errors` | Errors records any errors encountered when post-processing this snapshot, which includes the redaction of any potential PII. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Zone config events + +Events in this category pertain to zone configuration changes on +the SQL schema or system ranges. + +When zone configs apply to individual tables or other objects in a +SQL logical schema, they are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these zone config events are preserved +in each tenant's own `system.eventlog` table. + +When they apply to cluster-level ranges (e.g., the system zone config), +they are stored in the system tenant's own `system.eventlog` table. + +Events in this category are logged to the `OPS` channel. + + +### `remove_zone_config` + +An event of type `remove_zone_config` is recorded when a zone config is removed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `set_zone_config` + +An event of type `set_zone_config` is recorded when a zone config is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `ResolvedOldConfig` | The string representation of the resolved old zone config. This is not necessarily the same as the zone config that was previously set -- as it includes the resolved values of the zone config options. In other words, a zone config that hasn't been properly "set" yet (and inherits from its parent) will have a resolved_old_config that has details of the values it inherits from its parent. This is particularly useful to get a proper diff between the old and new zone config. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + + + + +## Enumeration types + +### `AuthFailReason` + +AuthFailReason is the inventory of possible reasons for an +authentication failure. + + +| Value | Textual alias in code or documentation | Description | +|--|--|--| +| 0 | UNKNOWN | is reported when the reason is unknown. | +| 1 | USER_RETRIEVAL_ERROR | occurs when there was an internal error accessing the principals. | +| 2 | USER_NOT_FOUND | occurs when the principal is unknown. | +| 3 | LOGIN_DISABLED | occurs when the user does not have LOGIN privileges. | +| 4 | METHOD_NOT_FOUND | occurs when no HBA rule matches or the method does not exist. | +| 5 | PRE_HOOK_ERROR | occurs when the authentication handshake encountered a protocol error. | +| 6 | CREDENTIALS_INVALID | occurs when the client-provided credentials were invalid. | +| 7 | CREDENTIALS_EXPIRED | occur when the credentials provided by the client are expired. | +| 8 | NO_REPLICATION_ROLEOPTION | occurs when the connection requires a replication role option, but the user does not have it. | +| 9 | AUTHORIZATION_ERROR | is used for errors during the authorization phase. For example, this would include issues with mapping LDAP groups to SQL roles and granting those roles to the user. | + + + diff --git a/src/current/_includes/cockroach-generated/release-24.3/logformats.md b/src/current/_includes/cockroach-generated/release-24.3/logformats.md new file mode 100644 index 00000000000..89580c9fc15 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.3/logformats.md @@ -0,0 +1,382 @@ + +The supported log output formats are documented below. + + +- [`crdb-v1`](#format-crdb-v1) + +- [`crdb-v1-count`](#format-crdb-v1-count) + +- [`crdb-v1-tty`](#format-crdb-v1-tty) + +- [`crdb-v1-tty-count`](#format-crdb-v1-tty-count) + +- [`crdb-v2`](#format-crdb-v2) + +- [`crdb-v2-tty`](#format-crdb-v2-tty) + +- [`json`](#format-json) + +- [`json-compact`](#format-json-compact) + +- [`json-fluent`](#format-json-fluent) + +- [`json-fluent-compact`](#format-json-fluent-compact) + + + +## Format `crdb-v1` + + +This is a legacy file format used from CockroachDB v1.0. + +Each log entry is emitted using a common prefix, described below, followed by: + +- The logging context tags enclosed between `[` and `]`, if any. It is possible + for this to be omitted if there were no context tags. +- Optionally, a counter column, if the option 'show-counter' is enabled. See below for details. +- the text of the log entry. + +Beware that the text of the log entry can span multiple lines. +The following caveats apply: + +- The text of the log entry can start with text enclosed between `[` and `]`. + If there were no logging tags to start with, it is not possible to distinguish between + logging context tag information and a `[...]` string in the main text of the + log entry. This means that this format is ambiguous. + + To remove this ambiguity, you can use the option 'show-counter'. + +- The text of the log entry can embed arbitrary application-level strings, + including strings that represent log entries. In particular, an accident + of implementation can cause the common entry prefix (described below) + to also appear on a line of its own, as part of the payload of a previous + log entry. There is no automated way to recognize when this occurs. + Care must be taken by a human observer to recognize these situations. + +- The log entry parser provided by CockroachDB to read log files is faulty + and is unable to recognize the aforementioned pitfall; nor can it read + entries larger than 64KiB successfully. Generally, use of this internal + log entry parser is discouraged for entries written with this format. + +See the newer format `crdb-v2` for an alternative +without these limitations. + +### Header lines + +At the beginning of each file, a header is printed using a similar format as +regular log entries. This header reports when the file was created, +which parameters were used to start the server, the server identifiers +if known, and other metadata about the running process. + +- This header appears to be logged at severity `INFO` (with an `I` prefix + at the start of the line) even though it does not really have a severity. +- The header is printed unconditionally even when a filter is configured to + omit entries at the `INFO` level. + +### Common log entry prefix + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker tags counter + +Reminder, the tags may be omitted; and the counter is only printed if the option +'show-counter' is specified. + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (omitted if zero for use by tests). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. | +| line | The line number where the entry originated. | +| marker | Redactability marker ` + redactableIndicator + ` (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. May be absent. | +| counter | The entry counter. Only included if 'show-counter' is enabled. | + +The redactability marker can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. + +If the marker ` + redactableIndicator + ` is present, the remainder of the log entry +contains delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `show-counter` | Whether to include the counter column in the line header. Without it, the format may be ambiguous due to the optionality of tags. | +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v1-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: none` + + +## Format `crdb-v1-tty` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: false` +- `colors: auto` + + +## Format `crdb-v1-tty-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: auto` + + +## Format `crdb-v2` + +This is the main file format used from CockroachDB v21.1. + +Each log entry is emitted using a common prefix, described below, +followed by the text of the log entry. + +### Entry format + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker [tags...] counter cont + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (zero when cannot be determined). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. Also see below. | +| line | The line number where the entry originated. | +| marker | Redactability marker "⋮" (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. See below. | +| counter | The optional entry counter (see below for details). | +| cont | Continuation mark for structured and multi-line entries. See below. | + +The `chan@` prefix before the file name indicates the logging channel, +and is omitted if the channel is `DEV`. + +The file name may be prefixed by the string `(gostd) ` to indicate +that the log entry was produced inside the Go standard library, instead +of a CockroachDB component. Entry parsers must be configured to ignore this prefix +when present. + +`marker` can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. +If the marker "⋮" is present, the remainder of the log entry +contains delimiters (‹...›) +around fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +when log redaction is requested. + +The logging `tags` are enclosed between square brackets `[...]`, +and the syntax `[-]` is used when there are no logging tags +associated with the log entry. + +`counter` is numeric, and is incremented for every +log entry emitted to this sink. (There is thus one counter sequence per +sink.) For entries that do not have a counter value +associated (e.g., header entries in file sinks), the counter position +in the common prefix is empty: `tags` is then +followed by two ASCII space characters, instead of one space; the `counter`, +and another space. The presence of the two ASCII spaces indicates +reliably that no counter was present. + +`cont` is a format/continuation indicator: + +| Continuation indicator | ASCII | Description | +|------------------------|-------|--| +| space | 0x32 | Start of an unstructured entry. | +| equal sign, "=" | 0x3d | Start of a structured entry. | +| exclamation mark, "!" | 0x21 | Start of an embedded stack trace. | +| plus sign, "+" | 0x2b | Continuation of a multi-line entry. The payload contains a newline character at this position. | +| vertical bar | 0x7c | Continuation of a large entry. | + +### Examples + +Example single-line unstructured entry: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 started with engine type ‹2› +~~~ + +Example multi-line unstructured entry: + +~~~ +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 node startup completed: +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 +CockroachDB node starting at 2021-01-16 21:49 (took 0.0s) +~~~ + +Example structured entry: + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventType":"node_restart"} +~~~ + +Example long entries broken up into multiple lines: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.... +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 |aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +~~~ + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventTy... +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 |pe":"node_restart"} +~~~ + +### Backward-compatibility notes + +Entries in this format can be read by most `crdb-v1` log parsers, +in particular the one included in the DB console and +also the [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +facility. + +However, implementers of previous version parsers must +understand that the logging tags field is now always +included, and the lack of logging tags is included +by a tag string set to `[-]`. + +Likewise, the entry counter is now also always included, +and there is a special character after `counter` +to indicate whether the remainder of the line is a +structured entry, or a continuation of a previous entry. + +Finally, in the previous format, structured entries +were prefixed with the string `Structured entry: `. In +the new format, they are prefixed by the `=` continuation +indicator. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v2-tty` + +This format name is an alias for 'crdb-v2' with +the following format option defaults: + +- `colors: auto` + + +## Format `json` + +This format emits log entries as a JSON payload. + +The JSON object is guaranteed to not contain unescaped newlines +or other special characters, and the entry as a whole is followed +by a newline character. This makes the format suitable for +processing over a stream unambiguously. + +Each entry contains at least the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `tag` | `tag` | (Only if the option `fluent-tag: true` is given.) A Fluent tag for the event, formed by the process name and the logging channel. | +| `d` | `datetime` | The pretty-printed date/time of the event timestamp, if enabled via options. | +| `f` | `file` | The name of the source file where the event was emitted. | +| `g` | `goroutine` | The identifier of the goroutine where the event was emitted. | +| `l` | `line` | The line number where the event was emitted in the source. | +| `r` | `redactable` | Whether the payload is redactable (see below for details). | +| `t` | `timestamp` | The timestamp at which the event was emitted on the logging channel. | +| `v` | `version` | The binary version with which the event was generated. | + + +After a couple of *header* entries written at the beginning of each log sink, +all subsequent log entries also contain the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `C` | `channel` | The name of the logging channel where the event was sent. | +| `sev` | `severity` | The severity of the event. | +| `c` | `channel_numeric` | The numeric identifier for the logging channel where the event was sent. | +| `n` | `entry_counter` | The entry number on this logging sink, relative to the last process restart. | +| `s` | `severity_numeric` | The numeric value of the severity of the event. | + + +Additionally, the following fields are conditionally present: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `N` | `node_id` | The node ID where the event was generated, once known. Only reported for single-tenant or KV servers. | +| `x` | `cluster_id` | The cluster ID where the event was generated, once known. Only reported for single-tenant of KV servers. | +| `q` | `instance_id` | The SQL instance ID where the event was generated, once known. | +| `T` | `tenant_id` | The SQL tenant ID where the event was generated, once known. | +| `V` | `tenant_name` | The SQL virtual cluster where the event was generated, once known. | +| `tags` | `tags` | The logging context tags for the entry, if there were context tags. | +| `message` | `message` | For unstructured events, the flat text payload. | +| `event` | `event` | The logging event, if structured (see below for details). | +| `stacks` | `stacks` | Goroutine stacks, for fatal events. | + +When an entry is structured, the `event` field maps to a dictionary +whose structure is one of the documented structured events. See the [reference documentation](eventlog.html) +for structured events for a list of possible payloads. + +When the entry is marked as `redactable`, the `tags`, `message`, and/or `event` payloads +contain delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `datetime-format` | The format to use for the `datetime` field. The value can be one of `none`, `iso8601`/`rfc3339` (synonyms), or `rfc1123`. Default is `none`. | +| `datetime-timezone` | The timezone to use for the `datetime` field. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | +| `tag-style` | The tags to include in the envelope. The value can be `compact` (one letter tags) or `verbose` (long-form tags). Default is `verbose`. | +| `fluent-tag` | Whether to produce an additional field called `tag` for Fluent compatibility. Default is `false`. | + + + +## Format `json-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: false` +- `tag-style: compact` + + +## Format `json-fluent` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: verbose` + + +## Format `json-fluent-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: compact` + + diff --git a/src/current/_includes/cockroach-generated/release-24.3/logging.md b/src/current/_includes/cockroach-generated/release-24.3/logging.md new file mode 100644 index 00000000000..8b628dc2dd9 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.3/logging.md @@ -0,0 +1,179 @@ +## Logging levels (severities) + +### INFO + +The `INFO` severity is used for informational messages that do not +require action. + +### WARNING + +The `WARNING` severity is used for situations which may require special handling, +where normal operation is expected to resume automatically. + +### ERROR + +The `ERROR` severity is used for situations that require special handling, +where normal operation could not proceed as expected. +Other operations can continue mostly unaffected. + +### FATAL + +The `FATAL` severity is used for situations that require an immedate, hard +server shutdown. A report is also sent to telemetry if telemetry +is enabled. + + +## Logging channels + +### `DEV` + +The `DEV` channel is used during development to collect log +details useful for troubleshooting that fall outside the +scope of other channels. It is also the default logging +channel for events not associated with a channel. + +This channel is special in that there are no constraints as to +what may or may not be logged on it. Conversely, users in +production deployments are invited to not collect `DEV` logs in +centralized logging facilities, because they likely contain +sensitive operational data. +See [Configure logs](configure-logs.html#dev-channel). + +### `OPS` + +The `OPS` channel is used to report "point" operational events, +initiated by user operators or automation: + + - Operator or system actions on server processes: process starts, + stops, shutdowns, crashes (if they can be logged), + including each time: command-line parameters, current version being run + - Actions that impact the topology of a cluster: node additions, + removals, decommissions, etc. + - Job-related initiation or termination + - [Cluster setting](cluster-settings.html) changes + - [Zone configuration](configure-replication-zones.html) changes + +### `HEALTH` + +The `HEALTH` channel is used to report "background" operational +events, initiated by CockroachDB or reporting on automatic processes: + + - Current resource usage, including critical resource usage + - Node-node connection events, including connection errors and + gossip details + - Range and table leasing events + - Up- and down-replication, range unavailability + +### `STORAGE` + +The `STORAGE` channel is used to report low-level storage +layer events (RocksDB/Pebble). + +### `SESSIONS` + +The `SESSIONS` channel is used to report client network activity when enabled via +the `server.auth_log.sql_connections.enabled` and/or +`server.auth_log.sql_sessions.enabled` [cluster setting](cluster-settings.html): + + - Connections opened/closed + - Authentication events: logins, failed attempts + - Session and query cancellation + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_SCHEMA` + +The `SQL_SCHEMA` channel is used to report changes to the +SQL logical schema, excluding privilege and ownership changes +(which are reported separately on the `PRIVILEGES` channel) and +zone configuration changes (which go to the `OPS` channel). + +This includes: + + - Database/schema/table/sequence/view/type creation + - Adding/removing/changing table columns + - Changing sequence parameters + +`SQL_SCHEMA` events generally comprise changes to the schema that affect the +functional behavior of client apps using stored objects. + +### `USER_ADMIN` + +The `USER_ADMIN` channel is used to report changes +in users and roles, including: + + - Users added/dropped + - Changes to authentication credentials (e.g., passwords, validity, etc.) + - Role grants/revocations + - Role option grants/revocations + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `PRIVILEGES` + +The `PRIVILEGES` channel is used to report data +authorization changes, including: + + - Privilege grants/revocations on database, objects, etc. + - Object ownership changes + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SENSITIVE_ACCESS` + +The `SENSITIVE_ACCESS` channel is used to report SQL +data access to sensitive data: + + - Data access audit events (when table audit is enabled via + [ALTER TABLE ... EXPERIMENTAL_AUDIT](alter-table.html#experimental_audit)) + - Data access audit events (when role-based audit is enabled via + [`sql.log.user_audit` cluster setting](role-based-audit-logging.html#syntax-of-audit-settings)) + - SQL statements executed by users with the admin role + - Operations that write to system tables + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_EXEC` + +The `SQL_EXEC` channel is used to report SQL execution on +behalf of client connections: + + - Logical SQL statement executions (when enabled via the + `sql.log.all_statements.enabled` [cluster setting](cluster-settings.html)) + - uncaught Go panic errors during the execution of a SQL statement. + +### `SQL_PERF` + +The `SQL_PERF` channel is used to report SQL executions +that are marked as "out of the ordinary" +to facilitate performance investigations. +This includes the SQL "slow query log". + +Arguably, this channel overlaps with `SQL_EXEC`. +However, we keep both channels separate for backward compatibility +with versions prior to v21.1, where the corresponding events +were redirected to separate files. + +### `SQL_INTERNAL_PERF` + +The `SQL_INTERNAL_PERF` channel is like the `SQL_PERF` channel, but is aimed at +helping developers of CockroachDB itself. It exists as a separate +channel so as to not pollute the `SQL_PERF` logging output with +internal troubleshooting details. + +### `TELEMETRY` + +The `TELEMETRY` channel reports telemetry events. Telemetry events describe +feature usage within CockroachDB and anonymizes any application- +specific data. + +### `KV_DISTRIBUTION` + +The `KV_DISTRIBUTION` channel is used to report data distribution events, such as moving +replicas between stores in the cluster, or adding (removing) replicas to +ranges. + diff --git a/src/current/_includes/cockroach-generated/release-24.3/settings/settings.html b/src/current/_includes/cockroach-generated/release-24.3/settings/settings.html new file mode 100644 index 00000000000..41cb4991d60 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.3/settings/settings.html @@ -0,0 +1,371 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingTypeDefaultDescriptionSupported Deployments
admission.disk_bandwidth_tokens.elastic.enabled
booleantruewhen true, and provisioned bandwidth for the disk corresponding to a store is configured, tokens for elastic work will be limited if disk bandwidth becomes a bottleneckDedicated/Self-Hosted
admission.epoch_lifo.enabled
booleanfalsewhen true, epoch-LIFO behavior is enabled when there is significant delay in admissionServerless/Dedicated/Self-Hosted
admission.epoch_lifo.epoch_closing_delta_duration
duration5msthe delta duration before closing an epoch, for epoch-LIFO admission control orderingServerless/Dedicated/Self-Hosted
admission.epoch_lifo.epoch_duration
duration100msthe duration of an epoch, for epoch-LIFO admission control orderingServerless/Dedicated/Self-Hosted
admission.epoch_lifo.queue_delay_threshold_to_switch_to_lifo
duration105msthe queue delay encountered by a (tenant,priority) for switching to epoch-LIFO orderingServerless/Dedicated/Self-Hosted
admission.kv.enabled
booleantruewhen true, work performed by the KV layer is subject to admission controlDedicated/Self-Hosted
admission.sql_kv_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a KV response is subject to admission controlServerless/Dedicated/Self-Hosted
admission.sql_sql_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a DistSQL response is subject to admission controlServerless/Dedicated/Self-Hosted
bulkio.backup.deprecated_full_backup_with_subdir.enabled
booleanfalsewhen true, a backup command with a user specified subdirectory will create a full backup at the subdirectory if no backup already exists at that subdirectoryServerless/Dedicated/Self-Hosted
bulkio.backup.file_size
byte size128 MiBtarget size for individual data files produced during BACKUPServerless/Dedicated/Self-Hosted
bulkio.backup.read_timeout
duration5m0samount of time after which a read attempt is considered timed out, which causes the backup to failServerless/Dedicated/Self-Hosted
bulkio.backup.read_with_priority_after
duration1m0samount of time since the read-as-of time above which a BACKUP should use priority when retrying readsServerless/Dedicated/Self-Hosted
physical_replication.consumer.minimum_flush_interval
(alias: bulkio.stream_ingestion.minimum_flush_interval)
duration5sthe minimum timestamp between flushes; flushes may still occur if internal buffers fill upDedicated/Self-Hosted
changefeed.aggregator.flush_jitter
float0.1jitter aggregator flushes as a fraction of min_checkpoint_frequency. This setting has no effect if min_checkpoint_frequency is set to 0.Serverless/Dedicated/Self-Hosted
changefeed.backfill.concurrent_scan_requests
integer0number of concurrent scan requests per node issued during a backfillServerless/Dedicated/Self-Hosted
changefeed.backfill.scan_request_size
integer524288the maximum number of bytes returned by each scan requestServerless/Dedicated/Self-Hosted
changefeed.batch_reduction_retry.enabled
(alias: changefeed.batch_reduction_retry_enabled)
booleanfalseif true, kafka changefeeds upon erroring on an oversized batch will attempt to resend the messages with progressively lower batch sizesServerless/Dedicated/Self-Hosted
changefeed.default_range_distribution_strategy
enumerationdefaultconfigures how work is distributed among nodes for a given changefeed. for the most balanced distribution, use `balanced_simple`. changing this setting will not override locality restrictions [default = 0, balanced_simple = 1]Serverless/Dedicated/Self-Hosted
changefeed.event_consumer_worker_queue_size
integer16if changefeed.event_consumer_workers is enabled, this setting sets the maxmimum number of events which a worker can bufferServerless/Dedicated/Self-Hosted
changefeed.event_consumer_workers
integer0the number of workers to use when processing events: <0 disables, 0 assigns a reasonable default, >0 assigns the setting value. for experimental/core changefeeds and changefeeds using parquet format, this is disabledServerless/Dedicated/Self-Hosted
changefeed.fast_gzip.enabled
booleantrueuse fast gzip implementationServerless/Dedicated/Self-Hosted
changefeed.frontier_highwater_lag_checkpoint_threshold
duration10m0scontrols the maximum the high-water mark is allowed to lag behind the leading spans of the frontier before per-span checkpointing is enabled; if 0, checkpointing due to high-water lag is disabledServerless/Dedicated/Self-Hosted
changefeed.kafka.max_request_size
byte size256 MiBthe maximum number of uncompressed bytes sent in a single request to a Kafka broker; lowering this value helps avoid spurious "message too large" errors that can occur when multiple messages are combined into a single batch; this setting is overridden by the per-changefeed Flush { MaxBytes: <int> } optionServerless/Dedicated/Self-Hosted
changefeed.kafka_v2_error_details.enabled
booleanfalseif enabled, Kafka v2 sinks will include the message key, size, and MVCC timestamp in message too large errorsServerless/Dedicated/Self-Hosted
changefeed.memory.per_changefeed_limit
byte size512 MiBcontrols amount of data that can be buffered per changefeedServerless/Dedicated/Self-Hosted
changefeed.min_highwater_advance
duration0sminimum amount of time the changefeed high water mark must advance for it to be eligible for checkpointing; Default of 0 will checkpoint every time frontier advances, as long as the rate of checkpointing keeps up with the rate of frontier changesServerless/Dedicated/Self-Hosted
changefeed.node_throttle_config
stringspecifies node level throttling configuration for all changefeeedsServerless/Dedicated/Self-Hosted
changefeed.protect_timestamp.max_age
duration96h0m0sfail the changefeed if the protected timestamp age exceeds this threshold; 0 disables expirationServerless/Dedicated/Self-Hosted
changefeed.protect_timestamp_interval
duration10m0scontrols how often the changefeed forwards its protected timestamp to the resolved timestampServerless/Dedicated/Self-Hosted
changefeed.schema_feed.read_with_priority_after
duration1m0sretry with high priority if we were not able to read descriptors for too long; 0 disablesServerless/Dedicated/Self-Hosted
changefeed.sink_io_workers
integer0the number of workers used by changefeeds when sending requests to the sink (currently the batching versions of webhook, pubsub, and kafka sinks that are enabled by changefeed.new_<sink type>_sink_enabled only): <0 disables, 0 assigns a reasonable default, >0 assigns the setting valueServerless/Dedicated/Self-Hosted
cloudstorage.azure.concurrent_upload_buffers
integer1controls the number of concurrent buffers that will be used by the Azure client when uploading chunks.Each buffer can buffer up to cloudstorage.write_chunk.size of memory during an uploadServerless/Dedicated/Self-Hosted
cloudstorage.azure.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.azure.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.azure.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.azure.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.gs.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.gs.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.gs.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.gs.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.http.custom_ca
stringcustom root CA (appended to system's default CAs) for verifying certificates when interacting with HTTPS storageServerless/Dedicated/Self-Hosted
cloudstorage.http.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.http.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.http.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.http.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nodelocal.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nodelocal.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nodelocal.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nodelocal.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nullsink.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nullsink.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nullsink.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nullsink.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.s3.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.s3.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.s3.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.s3.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.timeout
duration10m0sthe timeout for import/export storage operationsServerless/Dedicated/Self-Hosted
cloudstorage.userfile.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.userfile.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.userfile.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.userfile.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cluster.auto_upgrade.enabled
booleantruedisable automatic cluster version upgrade until resetServerless/Dedicated/Self-Hosted
cluster.organization
stringorganization nameDedicated/Self-hosted (read-write); Serverless (read-only)
cluster.preserve_downgrade_option
stringdisable (automatic or manual) cluster version upgrade from the specified version until resetServerless/Dedicated/Self-Hosted
debug.zip.redact_addresses.enabled
booleanfalseenables the redaction of hostnames and ip addresses in debug zipServerless/Dedicated/Self-Hosted
diagnostics.active_query_dumps.enabled
booleantrueexperimental: enable dumping of anonymized active queries to disk when node is under memory pressureDedicated/Self-hosted (read-write); Serverless (read-only)
diagnostics.forced_sql_stat_reset.interval
duration2h0m0sinterval after which the reported SQL Stats are reset even if not collected by telemetry reporter. It has a max value of 24H.Serverless/Dedicated/Self-Hosted
diagnostics.memory_monitoring_dumps.enabled
booleantrueenable dumping of memory monitoring state at the same time as heap profiles are takenDedicated/Self-hosted (read-write); Serverless (read-only)
diagnostics.reporting.enabled
booleantrueenable reporting diagnostic metrics to cockroach labs, but is ignored for Trial or Free licensesServerless/Dedicated/Self-Hosted
diagnostics.reporting.interval
duration1h0m0sinterval at which diagnostics data should be reportedServerless/Dedicated/Self-Hosted
enterprise.license
stringthe encoded cluster licenseDedicated/Self-hosted (read-write); Serverless (read-only)
external.graphite.endpoint
stringif nonempty, push server metrics to the Graphite or Carbon server at the specified host:portServerless/Dedicated/Self-Hosted
external.graphite.interval
duration10sthe interval at which metrics are pushed to Graphite (if enabled)Serverless/Dedicated/Self-Hosted
feature.backup.enabled
booleantrueset to true to enable backups, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.changefeed.enabled
booleantrueset to true to enable changefeeds, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.export.enabled
booleantrueset to true to enable exports, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.import.enabled
booleantrueset to true to enable imports, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.restore.enabled
booleantrueset to true to enable restore, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.schema_change.enabled
booleantrueset to true to enable schema changes, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.stats.enabled
booleantrueset to true to enable CREATE STATISTICS/ANALYZE, false to disable; default is trueServerless/Dedicated/Self-Hosted
jobs.retention_time
duration336h0m0sthe amount of time for which records for completed jobs are retainedServerless/Dedicated/Self-Hosted
kv.allocator.lease_rebalance_threshold
float0.05minimum fraction away from the mean a store's lease count can be before it is considered for lease-transfersDedicated/Self-Hosted
kv.allocator.load_based_lease_rebalancing.enabled
booleantrueset to enable rebalancing of range leases based on load and latencyDedicated/Self-Hosted
kv.allocator.load_based_rebalancing
enumerationleases and replicaswhether to rebalance based on the distribution of load across stores [off = 0, leases = 1, leases and replicas = 2]Dedicated/Self-Hosted
kv.allocator.load_based_rebalancing.objective
enumerationcpuwhat objective does the cluster use to rebalance; if set to `qps` the cluster will attempt to balance qps among stores, if set to `cpu` the cluster will attempt to balance cpu usage among stores [qps = 0, cpu = 1]Dedicated/Self-Hosted
kv.allocator.load_based_rebalancing_interval
duration1m0sthe rough interval at which each store will check for load-based lease / replica rebalancing opportunitiesDedicated/Self-Hosted
kv.allocator.qps_rebalance_threshold
float0.1minimum fraction away from the mean a store's QPS (such as queries per second) can be before it is considered overfull or underfullDedicated/Self-Hosted
kv.allocator.range_rebalance_threshold
float0.05minimum fraction away from the mean a store's range count can be before it is considered overfull or underfullDedicated/Self-Hosted
kv.allocator.store_cpu_rebalance_threshold
float0.1minimum fraction away from the mean a store's cpu usage can be before it is considered overfull or underfullDedicated/Self-Hosted
kv.bulk_io_write.max_rate
byte size1.0 TiBthe rate limit (bytes/sec) to use for writes to disk on behalf of bulk io opsDedicated/Self-Hosted
kv.bulk_sst.max_allowed_overage
byte size64 MiBif positive, allowed size in excess of target size for SSTs from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryDedicated/Self-Hosted
kv.bulk_sst.target_size
byte size16 MiBtarget size for SSTs emitted from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryDedicated/Self-hosted (read-write); Serverless (read-only)
kv.closed_timestamp.follower_reads.enabled
(alias: kv.closed_timestamp.follower_reads_enabled)
booleantrueallow (all) replicas to serve consistent historical reads based on closed timestamp informationDedicated/Self-hosted (read-write); Serverless (read-only)
kv.closed_timestamp.lead_for_global_reads_override
duration0sif nonzero, overrides the lead time that global_read ranges use to publish closed timestampsDedicated/Self-hosted (read-write); Serverless (read-only)
kv.closed_timestamp.side_transport_interval
duration200msthe interval at which the closed timestamp side-transport attempts to advance each range's closed timestamp; set to 0 to disable the side-transportDedicated/Self-hosted (read-write); Serverless (read-only)
kv.closed_timestamp.target_duration
duration3sif nonzero, attempt to provide closed timestamp notifications for timestamps trailing cluster time by approximately this durationDedicated/Self-hosted (read-write); Serverless (read-only)
kv.dist_sender.circuit_breaker.cancellation.enabled
booleantruewhen enabled, in-flight requests will be cancelled when the circuit breaker tripsServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.cancellation.write_grace_period
duration10show long after the circuit breaker trips to cancel write requests (these can't retry internally, so should be long enough to allow quorum/lease recovery)Serverless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.probe.interval
duration3sinterval between replica probesServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.probe.threshold
duration3sduration of errors or stalls after which a replica will be probedServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.probe.timeout
duration3stimeout for replica probesServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breakers.mode
enumerationliveness range onlyset of ranges to trip circuit breakers for failing or stalled replicas [no ranges = 0, liveness range only = 1, all ranges = 2]Serverless/Dedicated/Self-Hosted
kv.lease_transfer_read_summary.global_budget
byte size0 Bcontrols the maximum number of bytes that will be used to summarize the global segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Dedicated/Self-Hosted
kv.lease_transfer_read_summary.local_budget
byte size4.0 MiBcontrols the maximum number of bytes that will be used to summarize the local segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Dedicated/Self-Hosted
kv.log_range_and_node_events.enabled
booleantrueset to true to transactionally log range events (e.g., split, merge, add/remove voter/non-voter) into system.rangelogand node join and restart events into system.eventologDedicated/Self-Hosted
kv.protectedts.reconciliation.interval
duration5m0sthe frequency for reconciling jobs with protected timestamp recordsDedicated/Self-hosted (read-write); Serverless (read-only)
kv.raft.leader_fortification.fraction_enabled
float0controls the fraction of ranges for which the raft leader fortification protocol is enabled. Leader fortification is needed for a range to use a Leader lease. Set to 0.0 to disable leader fortification and, by extension, Leader leases. Set to 1.0 to enable leader fortification for all ranges and, by extension, use Leader leases for all ranges which do not require expiration-based leases. Set to a value between 0.0 and 1.0 to gradually roll out Leader leases across the ranges in a cluster.Dedicated/Self-Hosted
kv.range.range_size_hard_cap
byte size8.0 GiBhard cap on the maximum size a range is allowed to grow to withoutsplitting before writes to the range are blocked. Takes precedence over all other configurationsDedicated/Self-Hosted
kv.range_split.by_load.enabled
(alias: kv.range_split.by_load_enabled)
booleantrueallow automatic splits of ranges based on where load is concentratedDedicated/Self-Hosted
kv.range_split.load_cpu_threshold
duration500msthe CPU use per second over which, the range becomes a candidate for load based splittingDedicated/Self-Hosted
kv.range_split.load_qps_threshold
integer2500the QPS over which, the range becomes a candidate for load based splittingDedicated/Self-Hosted
kv.rangefeed.client.stream_startup_rate
integer100controls the rate per second the client will initiate new rangefeed stream for a single range; 0 implies unlimitedServerless/Dedicated/Self-Hosted
kv.rangefeed.closed_timestamp_refresh_interval
duration3sthe interval at which closed-timestamp updatesare delivered to rangefeeds; set to 0 to use kv.closed_timestamp.side_transport_intervalDedicated/Self-hosted (read-write); Serverless (read-only)
kv.rangefeed.enabled
booleanfalseif set, rangefeed registration is enabledDedicated/Self-hosted (read-write); Serverless (read-only)
kv.replica_circuit_breaker.slow_replication_threshold
duration1m0sduration after which slow proposals trip the per-Replica circuit breaker (zero duration disables breakers)Dedicated/Self-Hosted
kv.replica_stats.addsst_request_size_factor
integer50000the divisor that is applied to addsstable request sizes, then recorded in a leaseholders QPS; 0 means all requests are treated as cost 1Dedicated/Self-Hosted
kv.replication_reports.interval
duration1m0sthe frequency for generating the replication_constraint_stats, replication_stats_report and replication_critical_localities reports (set to 0 to disable)Dedicated/Self-Hosted
kv.snapshot_rebalance.max_rate
byte size32 MiBthe rate limit (bytes/sec) to use for rebalance and upreplication snapshotsDedicated/Self-Hosted
kv.snapshot_receiver.excise.enabled
booleantrueset to false to disable excises in place of range deletions for KV snapshotsDedicated/Self-Hosted
kv.transaction.max_intents_and_locks
integer0maximum count of inserts or durable locks for a single transactions, 0 to disableServerless/Dedicated/Self-Hosted
kv.transaction.max_intents_bytes
integer4194304maximum number of bytes used to track locks in transactionsServerless/Dedicated/Self-Hosted
kv.transaction.max_refresh_spans_bytes
integer4194304maximum number of bytes used to track refresh spans in serializable transactionsServerless/Dedicated/Self-Hosted
kv.transaction.randomized_anchor_key.enabled
booleanfalsedictates whether a transactions anchor key is randomized or notServerless/Dedicated/Self-Hosted
kv.transaction.reject_over_max_intents_budget.enabled
booleanfalseif set, transactions that exceed their lock tracking budget (kv.transaction.max_intents_bytes) are rejected instead of having their lock spans imprecisely compressedServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.locking_reads.enabled
booleantrueif enabled, transactional locking reads are pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.ranged_writes.enabled
booleantrueif enabled, transactional ranged writes are pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.enabled
(alias: kv.transaction.write_pipelining_enabled)
booleantrueif enabled, transactional writes are pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.max_batch_size
(alias: kv.transaction.write_pipelining_max_batch_size)
integer128if non-zero, defines that maximum size batch that will be pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kvadmission.store.provisioned_bandwidth
byte size0 Bif set to a non-zero value, this is used as the provisioned bandwidth (in bytes/s), for each store. It can be overridden on a per-store basis using the --store flag. Note that setting the provisioned bandwidth to a positive value may enable disk bandwidth based admission control, since admission.disk_bandwidth_tokens.elastic.enabled defaults to trueDedicated/Self-Hosted
kvadmission.store.snapshot_ingest_bandwidth_control.enabled
booleanfalseif set to true, snapshot ingests will be subject to disk write control in ACDedicated/Self-Hosted
obs.tablemetadata.automatic_updates.enabled
booleanfalseenables automatic updates of the table metadata cache system.table_metadataServerless/Dedicated/Self-Hosted
obs.tablemetadata.data_valid_duration
duration20m0sthe duration for which the data in system.table_metadata is considered validServerless/Dedicated/Self-Hosted
schedules.backup.gc_protection.enabled
booleantrueenable chaining of GC protection across backups run as part of a scheduleServerless/Dedicated/Self-Hosted
security.client_cert.subject_required.enabled
booleanfalsemandates a requirement for subject role to be set for db userDedicated/Self-hosted (read-write); Serverless (read-only)
security.ocsp.mode
enumerationoffuse OCSP to check whether TLS certificates are revoked. If the OCSP server is unreachable, in strict mode all certificates will be rejected and in lax mode all certificates will be accepted. [off = 0, lax = 1, strict = 2]Serverless/Dedicated/Self-Hosted
security.ocsp.timeout
duration3stimeout before considering the OCSP server unreachableServerless/Dedicated/Self-Hosted
server.auth_log.sql_connections.enabled
booleanfalseif set, log SQL client connect and disconnect events to the SESSIONS log channel (note: may hinder performance on loaded nodes)Serverless/Dedicated/Self-Hosted
server.auth_log.sql_sessions.enabled
booleanfalseif set, log verbose SQL session authentication events to the SESSIONS log channel (note: may hinder performance on loaded nodes). Session start and end events are always logged regardless of this setting; disable the SESSIONS log channel to suppress them.Serverless/Dedicated/Self-Hosted
server.authentication_cache.enabled
booleantrueenables a cache used during authentication to avoid lookups to system tables when retrieving per-user authentication-related informationServerless/Dedicated/Self-Hosted
server.child_metrics.enabled
booleanfalseenables the exporting of child metrics, additional prometheus time series with extra labelsServerless/Dedicated/Self-Hosted
server.child_metrics.include_aggregate.enabled
booleantrueinclude the reporting of the aggregate time series when child metrics are enabled. This cluster setting has no effect if child metrics are disabled.Serverless/Dedicated/Self-Hosted
server.client_cert_expiration_cache.capacity
integer1000the maximum number of client cert expirations storedServerless/Dedicated/Self-Hosted
server.clock.forward_jump_check.enabled
(alias: server.clock.forward_jump_check_enabled)
booleanfalseif enabled, forward clock jumps > max_offset/2 will cause a panicServerless/Dedicated/Self-Hosted
server.clock.persist_upper_bound_interval
duration0sthe interval between persisting the wall time upper bound of the clock. The clock does not generate a wall time greater than the persisted timestamp and will panic if it sees a wall time greater than this value. When cockroach starts, it waits for the wall time to catch-up till this persisted timestamp. This guarantees monotonic wall time across server restarts. Not setting this or setting a value of 0 disables this feature.Serverless/Dedicated/Self-Hosted
server.consistency_check.max_rate
byte size8.0 MiBthe rate limit (bytes/sec) to use for consistency checks; used in conjunction with server.consistency_check.interval to control the frequency of consistency checks. Note that setting this too high can negatively impact performance.Dedicated/Self-Hosted
server.eventlog.enabled
booleantrueif set, logged notable events are also stored in the table system.eventlogServerless/Dedicated/Self-Hosted
server.eventlog.ttl
duration2160h0m0sif nonzero, entries in system.eventlog older than this duration are periodically purgedServerless/Dedicated/Self-Hosted
server.host_based_authentication.configuration
stringhost-based authentication configuration to use during connection authenticationServerless/Dedicated/Self-Hosted
server.hot_ranges_request.node.timeout
duration5m0sthe duration allowed for a single node to return hot range data before the request is cancelled; if set to 0, there is no timeoutServerless/Dedicated/Self-Hosted
server.hsts.enabled
booleanfalseif true, HSTS headers will be sent along with all HTTP requests. The headers will contain a max-age setting of one year. Browsers honoring the header will always use HTTPS to access the DB Console. Ensure that TLS is correctly configured prior to enabling.Serverless/Dedicated/Self-Hosted
server.http.base_path
string/path to redirect the user to upon succcessful loginServerless/Dedicated/Self-Hosted
server.identity_map.configuration
stringsystem-identity to database-username mappingsServerless/Dedicated/Self-Hosted
server.jwt_authentication.audience
stringsets accepted audience values for JWT logins over the SQL interfaceServerless/Dedicated/Self-Hosted
server.jwt_authentication.claim
stringsets the JWT claim that is parsed to get the usernameServerless/Dedicated/Self-Hosted
server.jwt_authentication.client.timeout
duration15ssets the client timeout for external calls made during JWT authentication (e.g. fetching JWKS, etc.)Serverless/Dedicated/Self-Hosted
server.jwt_authentication.enabled
booleanfalseenables or disables JWT login for the SQL interfaceServerless/Dedicated/Self-Hosted
server.jwt_authentication.issuers.configuration
(alias: server.jwt_authentication.issuers)
stringsets accepted issuer values for JWT logins over the SQL interface which can be a single issuer URL string or a JSON string containing an array of issuer URLs or a JSON object containing map of issuer URLS to JWKS URIsServerless/Dedicated/Self-Hosted
server.jwt_authentication.issuers.custom_ca
stringsets the PEM encoded custom root CA for verifying certificates while fetching JWKSServerless/Dedicated/Self-Hosted
server.jwt_authentication.jwks
string{"keys":[]}sets the public key set for JWT logins over the SQL interface (JWKS format)Serverless/Dedicated/Self-Hosted
server.jwt_authentication.jwks_auto_fetch.enabled
booleanfalseenables or disables automatic fetching of JWKS from the issuer's well-known endpoint or JWKS URI set in JWTAuthIssuersConfig. If this is enabled, the server.jwt_authentication.jwks will be ignored.Serverless/Dedicated/Self-Hosted
server.ldap_authentication.client.tls_certificate
stringsets the client certificate PEM for establishing mTLS connection with LDAP serverServerless/Dedicated/Self-Hosted
server.ldap_authentication.client.tls_key
stringsets the client key PEM for establishing mTLS connection with LDAP serverServerless/Dedicated/Self-Hosted
server.ldap_authentication.domain.custom_ca
stringsets the PEM encoded custom root CA for verifying domain certificates when establishing connection with LDAP serverServerless/Dedicated/Self-Hosted
server.log_gc.max_deletions_per_cycle
integer1000the maximum number of entries to delete on each purge of log-like system tablesServerless/Dedicated/Self-Hosted
server.log_gc.period
duration1h0m0sthe period at which log-like system tables are checked for old entriesServerless/Dedicated/Self-Hosted
server.max_connections_per_gateway
integer-1the maximum number of SQL connections per gateway allowed at a given time (note: this will only limit future connection attempts and will not affect already established connections). Negative values result in unlimited number of connections. Superusers are not affected by this limit.Serverless/Dedicated/Self-Hosted
server.max_open_transactions_per_gateway
integer-1the maximum number of open SQL transactions per gateway allowed at a given time. Negative values result in unlimited number of connections. Superusers are not affected by this limit.Serverless/Dedicated/Self-Hosted
server.oidc_authentication.autologin.enabled
(alias: server.oidc_authentication.autologin)
booleanfalseif true, logged-out visitors to the DB Console will be automatically redirected to the OIDC login endpointServerless/Dedicated/Self-Hosted
server.oidc_authentication.button_text
stringLog in with your OIDC providertext to show on button on DB Console login page to login with your OIDC provider (only shown if OIDC is enabled)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.claim_json_key
stringsets JSON key of principal to extract from payload after OIDC authentication completes (usually email or sid)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.client.timeout
duration15ssets the client timeout for external calls made during OIDC authentication (e.g. authorization code flow, etc.)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.client_id
stringsets OIDC client idServerless/Dedicated/Self-Hosted
server.oidc_authentication.client_secret
stringsets OIDC client secretServerless/Dedicated/Self-Hosted
server.oidc_authentication.enabled
booleanfalseenables or disabled OIDC login for the DB ConsoleServerless/Dedicated/Self-Hosted
server.oidc_authentication.principal_regex
string(.+)regular expression to apply to extracted principal (see claim_json_key setting) to translate to SQL user (golang regex format, must include 1 grouping to extract)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.provider_url
stringsets OIDC provider URL ({provider_url}/.well-known/openid-configuration must resolve)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.redirect_url
stringhttps://localhost:8080/oidc/v1/callbacksets OIDC redirect URL via a URL string or a JSON string containing a required `redirect_urls` key with an object that maps from region keys to URL strings (URLs should point to your load balancer and must route to the path /oidc/v1/callback)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.scopes
stringopenidsets OIDC scopes to include with authentication request (space delimited list of strings, required to start with `openid`)Serverless/Dedicated/Self-Hosted
server.rangelog.ttl
duration720h0m0sif nonzero, entries in system.rangelog older than this duration are periodically purgedDedicated/Self-Hosted
server.redact_sensitive_settings.enabled
booleanfalseenables or disables the redaction of sensitive settings in the output of SHOW CLUSTER SETTINGS and SHOW ALL CLUSTER SETTINGS for users without the MODIFYCLUSTERSETTING privilegeServerless/Dedicated/Self-Hosted
server.shutdown.connections.timeout
(alias: server.shutdown.connection_wait)
duration0sthe maximum amount of time a server waits for all SQL connections to be closed before proceeding with a drain. (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Serverless/Dedicated/Self-Hosted
server.shutdown.initial_wait
(alias: server.shutdown.drain_wait)
duration0sthe amount of time a server waits in an unready state before proceeding with a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting. --drain-wait is to specify the duration of the whole draining process, while server.shutdown.initial_wait is to set the wait time for health probes to notice that the node is not ready.)Serverless/Dedicated/Self-Hosted
server.shutdown.lease_transfer_iteration.timeout
(alias: server.shutdown.lease_transfer_wait)
duration5sthe timeout for a single iteration of the range lease transfer phase of draining (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Dedicated/Self-Hosted
server.shutdown.transactions.timeout
(alias: server.shutdown.query_wait)
duration10sthe timeout for waiting for active transactions to finish during a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Serverless/Dedicated/Self-Hosted
server.sql_tcp_keep_alive.count
integer3maximum number of probes that will be sent out before a connection is dropped because it's unresponsive (Linux and Darwin only)Serverless/Dedicated/Self-Hosted
server.sql_tcp_keep_alive.interval
duration10stime between keep alive probes and idle time before probes are sent outServerless/Dedicated/Self-Hosted
server.time_until_store_dead
duration5m0sthe time after which if there is no new gossiped information about a store, it is considered deadServerless/Dedicated/Self-Hosted
server.user_login.cert_password_method.auto_scram_promotion.enabled
booleantruewhether to automatically promote cert-password authentication to use SCRAMServerless/Dedicated/Self-Hosted
server.user_login.downgrade_scram_stored_passwords_to_bcrypt.enabled
booleantrueif server.user_login.password_encryption=crdb-bcrypt, this controls whether to automatically re-encode stored passwords using scram-sha-256 to crdb-bcryptServerless/Dedicated/Self-Hosted
server.user_login.min_password_length
integer1the minimum length accepted for passwords set in cleartext via SQL. Note that a value lower than 1 is ignored: passwords cannot be empty in any case. This setting only applies when adding new users or altering an existing user's password; it will not affect existing logins.Serverless/Dedicated/Self-Hosted
server.user_login.password_encryption
enumerationscram-sha-256which hash method to use to encode cleartext passwords passed via ALTER/CREATE USER/ROLE WITH PASSWORD [crdb-bcrypt = 2, scram-sha-256 = 3]Serverless/Dedicated/Self-Hosted
server.user_login.password_hashes.default_cost.crdb_bcrypt
integer10the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method crdb-bcrypt (allowed range: 4-31)Serverless/Dedicated/Self-Hosted
server.user_login.password_hashes.default_cost.scram_sha_256
integer10610the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method scram-sha-256 (allowed range: 4096-240000000000)Serverless/Dedicated/Self-Hosted
server.user_login.rehash_scram_stored_passwords_on_cost_change.enabled
booleantrueif server.user_login.password_hashes.default_cost.scram_sha_256 differs from, the cost in a stored hash, this controls whether to automatically re-encode stored passwords using scram-sha-256 with the new default costServerless/Dedicated/Self-Hosted
server.user_login.timeout
duration10stimeout after which client authentication times out if some system range is unavailable (0 = no timeout)Serverless/Dedicated/Self-Hosted
server.user_login.upgrade_bcrypt_stored_passwords_to_scram.enabled
booleantrueif server.user_login.password_encryption=scram-sha-256, this controls whether to automatically re-encode stored passwords using crdb-bcrypt to scram-sha-256Serverless/Dedicated/Self-Hosted
server.web_session.purge.ttl
duration1h0m0sif nonzero, entries in system.web_sessions older than this duration are periodically purgedServerless/Dedicated/Self-Hosted
server.web_session.timeout
(alias: server.web_session_timeout)
duration168h0m0sthe duration that a newly created web session will be validServerless/Dedicated/Self-Hosted
spanconfig.bounds.enabled
booleantruedictates whether span config bounds are consulted when serving span configs for secondary tenantsDedicated/Self-Hosted
spanconfig.range_coalescing.system.enabled
(alias: spanconfig.storage_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs, for the ranges specific to the system tenantDedicated/Self-Hosted
spanconfig.range_coalescing.application.enabled
(alias: spanconfig.tenant_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs across all secondary tenant keyspacesDedicated/Self-Hosted
sql.auth.change_own_password.enabled
booleanfalsecontrols whether a user is allowed to change their own password, even if they have no other privilegesServerless/Dedicated/Self-Hosted
sql.auth.grant_option_for_owner.enabled
booleantruedetermines whether the GRANT OPTION for privileges is implicitly given to the owner of an objectServerless/Dedicated/Self-Hosted
sql.auth.grant_option_inheritance.enabled
booleantruedetermines whether the GRANT OPTION for privileges is inherited through role membershipServerless/Dedicated/Self-Hosted
sql.auth.public_schema_create_privilege.enabled
booleantruedetermines whether to grant all users the CREATE privileges on the public schema when it is createdServerless/Dedicated/Self-Hosted
sql.auth.skip_underlying_view_privilege_checks.enabled
booleantruedetermines whether to skip privilege checks on tables underlying views. When enabled, users with SELECT privileges on a view can query it regardless of their privileges on the underlying tables. This restores pre-v26.2 behavior.Serverless/Dedicated/Self-Hosted
sql.closed_session_cache.capacity
integer1000the maximum number of sessions in the cacheServerless/Dedicated/Self-Hosted
sql.closed_session_cache.time_to_live
integer3600the maximum time to live, in secondsServerless/Dedicated/Self-Hosted
sql.contention.event_store.capacity
byte size64 MiBthe in-memory storage capacity per-node of contention event storeServerless/Dedicated/Self-Hosted
sql.contention.event_store.duration_threshold
duration0sminimum contention duration to cause the contention events to be collected into crdb_internal.transaction_contention_eventsServerless/Dedicated/Self-Hosted
sql.contention.record_serialization_conflicts.enabled
booleantrueenables recording 40001 errors with conflicting txn meta as SERIALIZATION_CONFLICTcontention events into crdb_internal.transaction_contention_eventsServerless/Dedicated/Self-Hosted
sql.contention.txn_id_cache.max_size
byte size64 MiBthe maximum byte size TxnID cache will use (set to 0 to disable)Serverless/Dedicated/Self-Hosted
sql.cross_db_fks.enabled
booleanfalseif true, creating foreign key references across databases is allowedServerless/Dedicated/Self-Hosted
sql.cross_db_sequence_owners.enabled
booleanfalseif true, creating sequences owned by tables from other databases is allowedServerless/Dedicated/Self-Hosted
sql.cross_db_sequence_references.enabled
booleanfalseif true, sequences referenced by tables from other databases are allowedServerless/Dedicated/Self-Hosted
sql.cross_db_views.enabled
booleanfalseif true, creating views that refer to other databases is allowedServerless/Dedicated/Self-Hosted
sql.defaults.cost_scans_with_default_col_size.enabled
booleanfalsesetting to true uses the same size for all columns to compute scan cost
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.datestyle
enumerationiso, mdydefault value for DateStyle session setting [iso, mdy = 0, iso, dmy = 1, iso, ymd = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.default_hash_sharded_index_bucket_count
integer16used as bucket count if bucket count is not specified in hash sharded index definition
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.default_int_size
integer8the size, in bytes, of an INT type
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.disallow_full_table_scans.enabled
booleanfalsesetting to true rejects queries that have planned a full table scan; set large_full_scan_rows > 0 to allow small full table scans estimated to read fewer than large_full_scan_rows
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.distsql
enumerationautodefault distributed SQL execution mode [off = 0, auto = 1, on = 2, always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_alter_column_type.enabled
booleanfalsedefault value for experimental_alter_column_type session setting; enables the use of ALTER COLUMN TYPE for general conversions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_distsql_planning
enumerationoffdefault experimental_distsql_planning mode; enables experimental opt-driven DistSQL planning [off = 0, on = 1]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_enable_unique_without_index_constraints.enabled
booleanfalsedefault value for experimental_enable_unique_without_index_constraints session setting;disables unique without index constraints by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_implicit_column_partitioning.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for the use of implicit column partitioning
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_temporary_tables.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for use of temporary tables by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.foreign_key_cascades_limit
integer10000default value for foreign_key_cascades_limit session setting; limits the number of cascading operations that run as part of a single query
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.idle_in_session_timeout
duration0sdefault value for the idle_in_session_timeout; default value for the idle_in_session_timeout session setting; controls the duration a session is permitted to idle before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.idle_in_transaction_session_timeout
duration0sdefault value for the idle_in_transaction_session_timeout; controls the duration a session is permitted to idle in a transaction before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.implicit_select_for_update.enabled
booleantruedefault value for enable_implicit_select_for_update session setting; enables FOR UPDATE locking during the row-fetch phase of mutation statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.insert_fast_path.enabled
booleantruedefault value for enable_insert_fast_path session setting; enables a specialized insert path
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.intervalstyle
enumerationpostgresdefault value for IntervalStyle session setting [postgres = 0, iso_8601 = 1, sql_standard = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.large_full_scan_rows
float0default value for large_full_scan_rows session variable which determines the table size at which full scans are considered large and disallowed when disallow_full_table_scans is set to true; set to 0 to reject all full table or full index scans when disallow_full_table_scans is true
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.locality_optimized_partitioned_index_scan.enabled
booleantruedefault value for locality_optimized_partitioned_index_scan session setting; enables searching for rows in the current region before searching remote regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.lock_timeout
duration0sdefault value for the lock_timeout; default value for the lock_timeout session setting; controls the duration a query is permitted to wait while attempting to acquire a lock on a key or while blocking on an existing lock in order to perform a non-locking read on a key; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.on_update_rehome_row.enabled
booleantruedefault value for on_update_rehome_row; enables ON UPDATE rehome_row() expressions to trigger on updates
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.optimizer_use_histograms.enabled
booleantruedefault value for optimizer_use_histograms session setting; enables usage of histograms in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.optimizer_use_multicol_stats.enabled
booleantruedefault value for optimizer_use_multicol_stats session setting; enables usage of multi-column stats in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.override_alter_primary_region_in_super_region.enabled
booleanfalsedefault value for override_alter_primary_region_in_super_region; allows for altering the primary region even if the primary region is a member of a super region
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.override_multi_region_zone_config.enabled
booleanfalsedefault value for override_multi_region_zone_config; allows for overriding the zone configs of a multi-region table or database
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.prefer_lookup_joins_for_fks.enabled
booleanfalsedefault value for prefer_lookup_joins_for_fks session setting; causes foreign key operations to use lookup joins when possible
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.primary_region
stringif not empty, all databases created without a PRIMARY REGION will implicitly have the given PRIMARY REGION
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.reorder_joins_limit
integer8default number of joins to reorder
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.require_explicit_primary_keys.enabled
booleanfalsedefault value for requiring explicit primary keys in CREATE TABLE statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.results_buffer.size
byte size512 KiBdefault size of the buffer that accumulates results for a statement or a batch of statements before they are sent to the client. This can be overridden on an individual connection with the 'results_buffer_size' parameter. Note that auto-retries generally only happen while no results have been delivered to the client, so reducing this size can increase the number of retriable errors a client receives. On the other hand, increasing the buffer size can increase the delay until the client receives the first result row. Updating the setting only affects new connections. Setting to 0 disables any buffering.
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.serial_normalization
enumerationrowiddefault handling of SERIAL in table definitions [rowid = 0, virtual_sequence = 1, sql_sequence = 2, sql_sequence_cached = 3, unordered_rowid = 4, sql_sequence_cached_node = 5]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.statement_timeout
duration0sdefault value for the statement_timeout; default value for the statement_timeout session setting; controls the duration a query is permitted to run before it is canceled; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.stub_catalog_tables.enabled
booleantruedefault value for stub_catalog_tables session setting
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.super_regions.enabled
booleanfalsedefault value for enable_super_regions; allows for the usage of super regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_read_err
integer0the limit for the number of rows read by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_read_log
integer0the threshold for the number of rows read by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_written_err
integer0the limit for the number of rows written by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_written_log
integer0the threshold for the number of rows written by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.use_declarative_schema_changer
enumerationondefault value for use_declarative_schema_changer session setting;disables new schema changer by default [off = 0, on = 1, unsafe = 2, unsafe_always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.vectorize
enumerationondefault vectorize mode [on = 0, on = 1, on = 2, experimental_always = 3, off = 4]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.zigzag_join.enabled
booleanfalsedefault value for enable_zigzag_join session setting; disallows use of zig-zag join by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.distsql.temp_storage.workmem
byte size64 MiBmaximum amount of memory in bytes a processor can use before falling back to temp storageServerless/Dedicated/Self-Hosted
sql.guardrails.max_row_size_err
byte size512 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an error is returned; use 0 to disableServerless/Dedicated/Self-Hosted
sql.guardrails.max_row_size_log
byte size64 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an event is logged to SQL_PERF (or SQL_INTERNAL_PERF if the mutating statement was internal); use 0 to disableServerless/Dedicated/Self-Hosted
sql.hash_sharded_range_pre_split.max
integer16max pre-split ranges to have when adding hash sharded index to an existing tableServerless/Dedicated/Self-Hosted
sql.index_recommendation.drop_unused_duration
duration168h0m0sthe index unused duration at which we begin to recommend dropping the indexServerless/Dedicated/Self-Hosted
sql.insights.anomaly_detection.enabled
booleantrueenable per-fingerprint latency recording and anomaly detectionServerless/Dedicated/Self-Hosted
sql.insights.anomaly_detection.latency_threshold
duration50msstatements must surpass this threshold to trigger anomaly detection and identificationServerless/Dedicated/Self-Hosted
sql.insights.anomaly_detection.memory_limit
byte size1.0 MiBthe maximum amount of memory allowed for tracking statement latenciesServerless/Dedicated/Self-Hosted
sql.insights.execution_insights_capacity
integer1000the size of the per-node store of execution insightsServerless/Dedicated/Self-Hosted
sql.insights.high_retry_count.threshold
integer10the number of retries a slow statement must have undergone for its high retry count to be highlighted as a potential problemServerless/Dedicated/Self-Hosted
sql.insights.latency_threshold
duration100msamount of time after which an executing statement is considered slow. Use 0 to disable.Serverless/Dedicated/Self-Hosted
sql.log.redact_names.enabled
booleanfalseif set, schema object identifers are redacted in SQL statements that appear in event logsServerless/Dedicated/Self-Hosted
sql.log.slow_query.experimental_full_table_scans.enabled
booleanfalsewhen set to true, statements that perform a full table/index scan will be logged to the slow query log even if they do not meet the latency threshold. Must have the slow query log enabled for this setting to have any effect.Serverless/Dedicated/Self-Hosted
sql.log.slow_query.internal_queries.enabled
booleanfalsewhen set to true, internal queries which exceed the slow query log threshold are logged to a separate log. Must have the slow query log enabled for this setting to have any effect.Serverless/Dedicated/Self-Hosted
sql.log.slow_query.latency_threshold
duration0swhen set to non-zero, log statements whose service latency exceeds the threshold to a secondary logger on each nodeServerless/Dedicated/Self-Hosted
sql.log.user_audit
stringuser/role-based audit logging configuration. An enterprise license is required for this cluster setting to take effect.Serverless/Dedicated/Self-Hosted
sql.log.user_audit.reduced_config.enabled
booleanfalseenables logic to compute a reduced audit configuration, computing the audit configuration only once at session start instead of at each SQL event. The tradeoff with the increase in performance (~5%), is that changes to the audit configuration (user role memberships/cluster setting) are not reflected within session. Users will need to start a new session to see these changes in their auditing behaviour.Serverless/Dedicated/Self-Hosted
sql.metrics.index_usage_stats.enabled
booleantruecollect per index usage statisticsServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_reported_stmt_fingerprints
integer100000the maximum number of reported statement fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_reported_txn_fingerprints
integer100000the maximum number of reported transaction fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_stmt_fingerprints
integer7500the maximum number of statement fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_txn_fingerprints
integer7500the maximum number of transaction fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.dump_to_logs.enabled
(alias: sql.metrics.statement_details.dump_to_logs)
booleanfalsedump collected statement statistics to node logs when periodically clearedServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.enabled
booleantruecollect per-statement query statisticsServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.gateway_node.enabled
booleanfalsesave the gateway node for each statement fingerprint. If false, the value will be stored as 0.Serverless/Dedicated/Self-Hosted
sql.metrics.statement_details.index_recommendation_collection.enabled
booleantruegenerate an index recommendation for each fingerprint IDServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.max_mem_reported_idx_recommendations
integer5000the maximum number of reported index recommendation info stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.plan_collection.enabled
booleanfalseperiodically save a logical plan for each fingerprintServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.plan_collection.period
duration5m0sthe time until a new logical plan is collectedServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.threshold
duration0sminimum execution time to cause statement statistics to be collected. If configured, no transaction stats are collected.Serverless/Dedicated/Self-Hosted
sql.metrics.transaction_details.enabled
booleantruecollect per-application transaction statisticsServerless/Dedicated/Self-Hosted
sql.multiple_modifications_of_table.enabled
booleanfalseif true, allow statements containing multiple INSERT ON CONFLICT, UPSERT, UPDATE, or DELETE subqueries modifying the same table, at the risk of data corruption if the same row is modified multiple times by a single statement (multiple INSERT subqueries without ON CONFLICT cannot cause corruption and are always allowed)Serverless/Dedicated/Self-Hosted
sql.multiregion.drop_primary_region.enabled
booleantrueallows dropping the PRIMARY REGION of a database if it is the last regionServerless/Dedicated/Self-Hosted
sql.notices.enabled
booleantrueenable notices in the server/client protocol being sentServerless/Dedicated/Self-Hosted
sql.optimizer.uniqueness_checks_for_gen_random_uuid.enabled
booleanfalseif enabled, uniqueness checks may be planned for mutations of UUID columns updated with gen_random_uuid(); otherwise, uniqueness is assumed due to near-zero collision probabilityServerless/Dedicated/Self-Hosted
sql.schema.telemetry.recurrence
string@weeklycron-tab recurrence for SQL schema telemetry jobDedicated/Self-hosted (read-write); Serverless (read-only)
sql.spatial.experimental_box2d_comparison_operators.enabled
booleanfalseenables the use of certain experimental box2d comparison operatorsServerless/Dedicated/Self-Hosted
sql.stats.activity.persisted_rows.max
integer200000maximum number of rows of statement and transaction activity that will be persisted in the system tablesServerless/Dedicated/Self-Hosted
sql.stats.automatic_collection.enabled
booleantrueautomatic statistics collection modeServerless/Dedicated/Self-Hosted
sql.stats.automatic_collection.fraction_stale_rows
float0.2target fraction of stale rows per table that will trigger a statistics refreshServerless/Dedicated/Self-Hosted
sql.stats.automatic_collection.min_stale_rows
integer500target minimum number of stale rows per table that will trigger a statistics refreshServerless/Dedicated/Self-Hosted
sql.stats.automatic_partial_collection.enabled
booleanfalseautomatic partial statistics collection modeServerless/Dedicated/Self-Hosted
sql.stats.automatic_partial_collection.fraction_stale_rows
float0.05target fraction of stale rows per table that will trigger a partial statistics refreshServerless/Dedicated/Self-Hosted
sql.stats.automatic_partial_collection.min_stale_rows
integer100target minimum number of stale rows per table that will trigger a partial statistics refreshServerless/Dedicated/Self-Hosted
sql.stats.cleanup.recurrence
string@hourlycron-tab recurrence for SQL Stats cleanup jobServerless/Dedicated/Self-Hosted
sql.stats.error_on_concurrent_create_stats.enabled
booleantrueset to true to error on concurrent CREATE STATISTICS jobs, instead of skipping themServerless/Dedicated/Self-Hosted
sql.stats.flush.enabled
booleantrueif set, SQL execution statistics are periodically flushed to diskServerless/Dedicated/Self-Hosted
sql.stats.flush.interval
duration10m0sthe interval at which SQL execution statistics are flushed to disk, this value must be less than or equal to 1 hourServerless/Dedicated/Self-Hosted
sql.stats.forecasts.enabled
booleantruewhen true, enables generation of statistics forecasts by default for all tablesServerless/Dedicated/Self-Hosted
sql.stats.forecasts.max_decrease
float0.3333333333333333the most a prediction is allowed to decrease, expressed as the minimum ratio of the prediction to the lowest prior observationServerless/Dedicated/Self-Hosted
sql.stats.forecasts.min_goodness_of_fit
float0.95the minimum R² (goodness of fit) measurement required from all predictive models to use a forecastServerless/Dedicated/Self-Hosted
sql.stats.forecasts.min_observations
integer3the mimimum number of observed statistics required to produce a statistics forecastServerless/Dedicated/Self-Hosted
sql.stats.histogram_buckets.count
integer200maximum number of histogram buckets to build during table statistics collectionServerless/Dedicated/Self-Hosted
sql.stats.histogram_buckets.include_most_common_values.enabled
booleantruewhether to include most common values as histogram bucketsServerless/Dedicated/Self-Hosted
sql.stats.histogram_buckets.max_fraction_most_common_values
float0.1maximum fraction of histogram buckets to use for most common valuesServerless/Dedicated/Self-Hosted
sql.stats.histogram_collection.enabled
booleantruehistogram collection modeServerless/Dedicated/Self-Hosted
sql.stats.histogram_samples.count
integer0number of rows sampled for histogram construction during table statistics collection. Not setting this or setting a value of 0 means that a reasonable sample size will be automatically picked based on the table size.Serverless/Dedicated/Self-Hosted
sql.stats.multi_column_collection.enabled
booleantruemulti-column statistics collection modeServerless/Dedicated/Self-Hosted
sql.stats.non_default_columns.min_retention_period
duration24h0m0sminimum retention period for table statistics collected on non-default columnsServerless/Dedicated/Self-Hosted
sql.stats.non_indexed_json_histograms.enabled
booleantrueset to true to collect table statistics histograms on non-indexed JSON columnsServerless/Dedicated/Self-Hosted
sql.stats.persisted_rows.max
integer1000000maximum number of rows of statement and transaction statistics that will be persisted in the system tables before compaction beginsServerless/Dedicated/Self-Hosted
sql.stats.post_events.enabled
booleanfalseif set, an event is logged for every CREATE STATISTICS jobServerless/Dedicated/Self-Hosted
sql.stats.response.max
integer20000the maximum number of statements and transaction stats returned in a CombinedStatements requestServerless/Dedicated/Self-Hosted
sql.stats.response.show_internal.enabled
booleanfalsecontrols if statistics for internal executions should be returned by the CombinedStatements and if internal sessions should be returned by the ListSessions endpoints. These endpoints are used to display statistics on the SQL Activity pagesServerless/Dedicated/Self-Hosted
sql.stats.system_tables.enabled
booleantruewhen true, enables use of statistics on system tables by the query optimizerServerless/Dedicated/Self-Hosted
sql.stats.system_tables_autostats.enabled
booleantruewhen true, enables automatic collection of statistics on system tablesServerless/Dedicated/Self-Hosted
sql.stats.virtual_computed_columns.enabled
booleantrueset to true to collect table statistics on virtual computed columnsServerless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.enabled
booleanfalsewhen set to true, executed queries will emit an event on the telemetry logging channelServerless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.internal.enabled
booleanfalsewhen set to true, internal queries will be sampled in telemetry loggingServerless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample executions for telemetry, note that it is recommended that this value shares a log-line limit of 10 logs per second on the telemetry pipeline with all other telemetry events. If sampling mode is set to 'transaction', this value is ignored.Serverless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.mode
enumerationstatementthe execution level used for telemetry sampling. If set to 'statement', events are sampled at the statement execution level. If set to 'transaction', events are sampled at the transaction execution level, i.e. all statements for a transaction will be logged and are counted together as one sampled event (events are still emitted one per statement). [statement = 0, transaction = 1]Serverless/Dedicated/Self-Hosted
sql.telemetry.transaction_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample transactions for telemetry. If sampling mode is set to 'statement', this setting is ignored. In practice, this means that we only sample a transaction if 1/max_event_frequency seconds have elapsed since the last transaction was sampled.Serverless/Dedicated/Self-Hosted
sql.telemetry.transaction_sampling.statement_events_per_transaction.max
integer50the maximum number of statement events to log for every sampled transaction. Note that statements that are logged by force do not adhere to this limit.Serverless/Dedicated/Self-Hosted
sql.temp_object_cleaner.cleanup_interval
duration30m0show often to clean up orphaned temporary objectsServerless/Dedicated/Self-Hosted
sql.temp_object_cleaner.wait_interval
duration30m0show long after creation a temporary object will be cleaned upServerless/Dedicated/Self-Hosted
sql.log.all_statements.enabled
(alias: sql.trace.log_statement_execute)
booleanfalseset to true to enable logging of all executed statementsServerless/Dedicated/Self-Hosted
sql.trace.stmt.enable_threshold
duration0senables tracing on all statements; statements executing for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting applies to individual statements within a transaction and is therefore finer-grained than sql.trace.txn.enable_thresholdServerless/Dedicated/Self-Hosted
sql.trace.txn.enable_threshold
duration0senables tracing on all transactions; transactions open for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting is coarser-grained than sql.trace.stmt.enable_threshold because it applies to all statements within a transaction as well as client communication (e.g. retries)Serverless/Dedicated/Self-Hosted
sql.ttl.changefeed_replication.disabled
booleanfalseif true, deletes issued by TTL will not be replicated via changefeeds (this setting will be ignored by changefeeds that have the ignore_disable_changefeed_replication option set; such changefeeds will continue to replicate all TTL deletes)Serverless/Dedicated/Self-Hosted
sql.ttl.default_delete_batch_size
integer100default amount of rows to delete in a single query during a TTL jobServerless/Dedicated/Self-Hosted
sql.ttl.default_delete_rate_limit
integer100default delete rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Serverless/Dedicated/Self-Hosted
sql.ttl.default_select_batch_size
integer500default amount of rows to select in a single query during a TTL jobServerless/Dedicated/Self-Hosted
sql.ttl.default_select_rate_limit
integer0default select rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Serverless/Dedicated/Self-Hosted
sql.ttl.job.enabled
booleantruewhether the TTL job is enabledServerless/Dedicated/Self-Hosted
sql.txn.read_committed_isolation.enabled
booleantrueset to true to allow transactions to use the READ COMMITTED isolation level if specified by BEGIN/SET commandsServerless/Dedicated/Self-Hosted
sql.txn.repeatable_read_isolation.enabled
(alias: sql.txn.snapshot_isolation.enabled)
booleanfalseset to true to allow transactions to use the REPEATABLE READ isolation level if specified by BEGIN/SET commandsServerless/Dedicated/Self-Hosted
sql.txn_fingerprint_id_cache.capacity
integer100the maximum number of txn fingerprint IDs storedServerless/Dedicated/Self-Hosted
storage.columnar_blocks.enabled
booleanfalseset to true to enable columnar-blocks to store KVs in a columnar format (experimental)Dedicated/Self-hosted (read-write); Serverless (read-only)
storage.delete_compaction_excise.enabled
booleantrueset to false to direct Pebble to not partially excise sstables in delete-only compactionsDedicated/Self-hosted (read-write); Serverless (read-only)
storage.experimental.eventually_file_only_snapshots.enabled
booleantrueset to false to disable eventually-file-only-snapshots (kv.snapshot_receiver.excise.enabled must also be false)Dedicated/Self-Hosted
storage.ingest_split.enabled
booleantrueset to false to disable ingest-time splitting that lowers write-amplificationDedicated/Self-Hosted
storage.ingestion.value_blocks.enabled
booleantrueset to true to enable writing of value blocks in ingestion sstablesServerless/Dedicated/Self-Hosted
storage.max_sync_duration
duration20smaximum duration for disk operations; any operations that take longer than this setting trigger a warning log entry or process crashDedicated/Self-hosted (read-write); Serverless (read-only)
storage.max_sync_duration.fatal.enabled
booleantrueif true, fatal the process when a disk operation exceeds storage.max_sync_durationServerless/Dedicated/Self-Hosted
storage.sstable.compression_algorithm
enumerationsnappydetermines the compression algorithm to use when compressing sstable data blocks for use in a Pebble store; [snappy = 1, zstd = 2, none = 3]Dedicated/Self-hosted (read-write); Serverless (read-only)
storage.sstable.compression_algorithm_backup_storage
enumerationsnappydetermines the compression algorithm to use when compressing sstable data blocks for backup row data storage; [snappy = 1, zstd = 2, none = 3]Dedicated/Self-hosted (read-write); Serverless (read-only)
storage.sstable.compression_algorithm_backup_transport
enumerationsnappydetermines the compression algorithm to use when compressing sstable data blocks for backup transport; [snappy = 1, zstd = 2, none = 3]Dedicated/Self-hosted (read-write); Serverless (read-only)
storage.wal_failover.unhealthy_op_threshold
duration100msthe latency of a WAL write considered unhealthy and triggers a failover to a secondary WAL locationDedicated/Self-Hosted
timeseries.storage.enabled
booleantrueif set, periodic timeseries data is stored within the cluster; disabling is not recommended unless you are storing the data elsewhereDedicated/Self-Hosted
timeseries.storage.resolution_10s.ttl
duration240h0m0sthe maximum age of time series data stored at the 10 second resolution. Data older than this is subject to rollup and deletion.Dedicated/Self-hosted (read-write); Serverless (read-only)
timeseries.storage.resolution_30m.ttl
duration2160h0m0sthe maximum age of time series data stored at the 30 minute resolution. Data older than this is subject to deletion.Dedicated/Self-hosted (read-write); Serverless (read-only)
trace.debug_http_endpoint.enabled
(alias: trace.debug.enable)
booleanfalseif set, traces for recent requests can be seen at https://<ui>/debug/requestsServerless/Dedicated/Self-Hosted
trace.opentelemetry.collector
stringaddress of an OpenTelemetry trace collector to receive traces using the otel gRPC protocol, as <host>:<port>. If no port is specified, 4317 will be used.Serverless/Dedicated/Self-Hosted
trace.snapshot.rate
duration0sif non-zero, interval at which background trace snapshots are capturedServerless/Dedicated/Self-Hosted
trace.span_registry.enabled
booleantrueif set, ongoing traces can be seen at https://<ui>/#/debug/tracezServerless/Dedicated/Self-Hosted
trace.zipkin.collector
stringthe address of a Zipkin instance to receive traces, as <host>:<port>. If no port is specified, 9411 will be used.Serverless/Dedicated/Self-Hosted
ui.display_timezone
enumerationetc/utcthe timezone used to format timestamps in the ui [etc/utc = 0, america/new_york = 1]Serverless/Dedicated/Self-Hosted
version
version24.3set the active cluster version in the format '<major>.<minor>'Serverless/Dedicated/Self-Hosted
diff --git a/src/current/_includes/cockroach-generated/release-24.3/sql/aggregates.md b/src/current/_includes/cockroach-generated/release-24.3/sql/aggregates.md new file mode 100644 index 00000000000..3213f0f02a8 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.3/sql/aggregates.md @@ -0,0 +1,579 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_agg(arg1: bool) → bool[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bool[]) → bool[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes) → bytes[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes[]) → bytes[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date) → date[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date[]) → date[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal) → decimal[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal[]) → decimal[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float) → float[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float[]) → float[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet) → inet[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet[]) → inet[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int) → int[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int[]) → int[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval) → interval[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval[]) → interval[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string) → string[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string[]) → string[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time) → time[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time[]) → time[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp) → timestamp[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp[]) → timestamp[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz) → timestamptz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz[]) → timestamptz[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid) → uuid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid[]) → uuid[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum) → anyenum[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum[]) → anyenum[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d) → box2d[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d[]) → box2d[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography) → geography[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography[]) → geography[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry) → geometry[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry[]) → geometry[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb) → jsonb[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb[]) → jsonb[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid) → oid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid[]) → oid[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn) → pg_lsn[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn[]) → pg_lsn[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor) → refcursor[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor[]) → refcursor[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz) → timetz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz[]) → timetz[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple) → tuple[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple[]) → tuple[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit) → varbit[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit[]) → varbit[][]

Aggregates the selected values into an array.

+		Immutable
array_cat_agg(arg1: bool[]) → bool[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: bytes[]) → bytes[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: date[]) → date[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: decimal[]) → decimal[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: float[]) → float[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: inet[]) → inet[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: int[]) → int[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: interval[]) → interval[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: string[]) → string[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: time[]) → time[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamp[]) → timestamp[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamptz[]) → timestamptz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: uuid[]) → uuid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: anyenum[]) → anyenum[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: box2d[]) → box2d[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geography[]) → geography[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geometry[]) → geometry[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: jsonb[]) → jsonb[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: oid[]) → oid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: pg_lsn[]) → pg_lsn[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: refcursor[]) → refcursor[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timetz[]) → timetz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: tuple[]) → tuple[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: varbit[]) → varbit[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
avg(arg1: decimal) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: float) → float

Calculates the average of the selected values.

+		Immutable
avg(arg1: int) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: interval) → interval

Calculates the average of the selected values.

+		Immutable
bit_and(arg1: int) → int

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_and(arg1: varbit) → varbit

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: int) → int

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: varbit) → varbit

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bool_and(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
bool_or(arg1: bool) → bool

Calculates the boolean value of ORing all selected values.

+		Immutable
concat_agg(arg1: bytes) → bytes

Concatenates all selected values.

+		Immutable
concat_agg(arg1: string) → string

Concatenates all selected values.

+		Immutable
corr(arg1: decimal, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
count(arg1: anyelement) → int

Calculates the number of selected elements.

+		Immutable
count_rows() → int

Calculates the number of rows.

+		Immutable
covar_pop(arg1: decimal, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
every(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
json_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
json_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
jsonb_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
jsonb_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
max(arg1: bool) → bool

Identifies the maximum selected value.

+		Immutable
max(arg1: bytes) → bytes

Identifies the maximum selected value.

+		Immutable
max(arg1: date) → date

Identifies the maximum selected value.

+		Immutable
max(arg1: decimal) → decimal

Identifies the maximum selected value.

+		Immutable
max(arg1: float) → float

Identifies the maximum selected value.

+		Immutable
max(arg1: inet) → inet

Identifies the maximum selected value.

+		Immutable
max(arg1: int) → int

Identifies the maximum selected value.

+		Immutable
max(arg1: interval) → interval

Identifies the maximum selected value.

+		Immutable
max(arg1: string) → string

Identifies the maximum selected value.

+		Immutable
max(arg1: time) → time

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamp) → timestamp

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamptz) → timestamptz

Identifies the maximum selected value.

+		Immutable
max(arg1: uuid) → uuid

Identifies the maximum selected value.

+		Immutable
max(arg1: anyenum) → anyenum

Identifies the maximum selected value.

+		Immutable
max(arg1: box2d) → box2d

Identifies the maximum selected value.

+		Immutable
max(arg1: collatedstring{*}) → collatedstring{*}

Identifies the maximum selected value.

+		Immutable
max(arg1: geography) → geography

Identifies the maximum selected value.

+		Immutable
max(arg1: geometry) → geometry

Identifies the maximum selected value.

+		Immutable
max(arg1: jsonb) → jsonb

Identifies the maximum selected value.

+		Immutable
max(arg1: oid) → oid

Identifies the maximum selected value.

+		Immutable
max(arg1: pg_lsn) → pg_lsn

Identifies the maximum selected value.

+		Immutable
max(arg1: timetz) → timetz

Identifies the maximum selected value.

+		Immutable
max(arg1: varbit) → varbit

Identifies the maximum selected value.

+		Immutable
min(arg1: bool) → bool

Identifies the minimum selected value.

+		Immutable
min(arg1: bytes) → bytes

Identifies the minimum selected value.

+		Immutable
min(arg1: date) → date

Identifies the minimum selected value.

+		Immutable
min(arg1: decimal) → decimal

Identifies the minimum selected value.

+		Immutable
min(arg1: float) → float

Identifies the minimum selected value.

+		Immutable
min(arg1: inet) → inet

Identifies the minimum selected value.

+		Immutable
min(arg1: int) → int

Identifies the minimum selected value.

+		Immutable
min(arg1: interval) → interval

Identifies the minimum selected value.

+		Immutable
min(arg1: string) → string

Identifies the minimum selected value.

+		Immutable
min(arg1: time) → time

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamp) → timestamp

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamptz) → timestamptz

Identifies the minimum selected value.

+		Immutable
min(arg1: uuid) → uuid

Identifies the minimum selected value.

+		Immutable
min(arg1: anyenum) → anyenum

Identifies the minimum selected value.

+		Immutable
min(arg1: box2d) → box2d

Identifies the minimum selected value.

+		Immutable
min(arg1: collatedstring{*}) → collatedstring{*}

Identifies the minimum selected value.

+		Immutable
min(arg1: geography) → geography

Identifies the minimum selected value.

+		Immutable
min(arg1: geometry) → geometry

Identifies the minimum selected value.

+		Immutable
min(arg1: jsonb) → jsonb

Identifies the minimum selected value.

+		Immutable
min(arg1: oid) → oid

Identifies the minimum selected value.

+		Immutable
min(arg1: pg_lsn) → pg_lsn

Identifies the minimum selected value.

+		Immutable
min(arg1: timetz) → timetz

Identifies the minimum selected value.

+		Immutable
min(arg1: varbit) → varbit

Identifies the minimum selected value.

+		Immutable
percentile_cont(arg1: float) → float

Continuous percentile: returns a float corresponding to the specified fraction in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float) → interval

Continuous percentile: returns an interval corresponding to the specified fraction in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_cont(arg1: float[]) → float[]

Continuous percentile: returns floats corresponding to the specified fractions in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float[]) → interval[]

Continuous percentile: returns intervals corresponding to the specified fractions in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_disc(arg1: float) → anyelement

Discrete percentile: returns the first input value whose position in the ordering equals or exceeds the specified fraction.

+		Immutable
percentile_disc(arg1: float[]) → anyelement

Discrete percentile: returns input values whose position in the ordering equals or exceeds the specified fractions.

+		Immutable
regr_avgx(arg1: decimal, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_count(arg1: decimal, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_intercept(arg1: decimal, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_r2(arg1: decimal, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_slope(arg1: decimal, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_sxx(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
sqrdiff(arg1: decimal) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: float) → float

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: int) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
st_collect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_extent(arg1: geometry) → box2d

Forms a Box2D that encapsulates all provided geometries.

+		Immutable
st_makeline(arg1: geometry) → geometry

Forms a LineString from Point, MultiPoint or LineStrings. Other shapes will be ignored.

+		Immutable
st_memcollect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_memunion(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
st_union(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
stddev(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: decimal) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: float) → float

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: int) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
string_agg(arg1: bytes, arg2: bytes) → bytes

Concatenates all selected values using the provided delimiter.

+		Immutable
string_agg(arg1: string, arg2: string) → string

Concatenates all selected values using the provided delimiter.

+		Immutable
sum(arg1: decimal) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: float) → float

Calculates the sum of the selected values.

+		Immutable
sum(arg1: int) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: interval) → interval

Calculates the sum of the selected values.

+		Immutable
sum_int(arg1: int) → int

Calculates the sum of the selected values.

+		Immutable
var_pop(arg1: decimal) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: float) → float

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: int) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_samp(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
variance(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
xor_agg(arg1: bytes) → bytes

Calculates the bitwise XOR of the selected values.

+		Immutable
xor_agg(arg1: int) → int

Calculates the bitwise XOR of the selected values.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-24.3/sql/functions.md b/src/current/_includes/cockroach-generated/release-24.3/sql/functions.md new file mode 100644 index 00000000000..1e734501429 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.3/sql/functions.md @@ -0,0 +1,3523 @@ +### Array functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_append(array: bool[], elem: bool) → bool[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: bytes[], elem: bytes) → bytes[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: date[], elem: date) → date[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: decimal[], elem: decimal) → decimal[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: float[], elem: float) → float[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: inet[], elem: inet) → inet[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: int[], elem: int) → int[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: interval[], elem: interval) → interval[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: string[], elem: string) → string[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: time[], elem: time) → time[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamp[], elem: timestamp) → timestamp[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamptz[], elem: timestamptz) → timestamptz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: uuid[], elem: uuid) → uuid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: anyenum[], elem: anyenum) → anyenum[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: box2d[], elem: box2d) → box2d[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geography[], elem: geography) → geography[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geometry[], elem: geometry) → geometry[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: jsonb[], elem: jsonb) → jsonb[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: oid[], elem: oid) → oid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: refcursor[], elem: refcursor) → refcursor[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timetz[], elem: timetz) → timetz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: tuple[], elem: tuple) → tuple[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: varbit[], elem: varbit) → varbit[]

Appends elem to array, returning the result.

+		Immutable
array_cat(left: bool[], right: bool[]) → bool[]

Appends two arrays.

+		Immutable
array_cat(left: bytes[], right: bytes[]) → bytes[]

Appends two arrays.

+		Immutable
array_cat(left: date[], right: date[]) → date[]

Appends two arrays.

+		Immutable
array_cat(left: decimal[], right: decimal[]) → decimal[]

Appends two arrays.

+		Immutable
array_cat(left: float[], right: float[]) → float[]

Appends two arrays.

+		Immutable
array_cat(left: inet[], right: inet[]) → inet[]

Appends two arrays.

+		Immutable
array_cat(left: int[], right: int[]) → int[]

Appends two arrays.

+		Immutable
array_cat(left: interval[], right: interval[]) → interval[]

Appends two arrays.

+		Immutable
array_cat(left: string[], right: string[]) → string[]

Appends two arrays.

+		Immutable
array_cat(left: time[], right: time[]) → time[]

Appends two arrays.

+		Immutable
array_cat(left: timestamp[], right: timestamp[]) → timestamp[]

Appends two arrays.

+		Immutable
array_cat(left: timestamptz[], right: timestamptz[]) → timestamptz[]

Appends two arrays.

+		Immutable
array_cat(left: uuid[], right: uuid[]) → uuid[]

Appends two arrays.

+		Immutable
array_cat(left: anyenum[], right: anyenum[]) → anyenum[]

Appends two arrays.

+		Immutable
array_cat(left: box2d[], right: box2d[]) → box2d[]

Appends two arrays.

+		Immutable
array_cat(left: geography[], right: geography[]) → geography[]

Appends two arrays.

+		Immutable
array_cat(left: geometry[], right: geometry[]) → geometry[]

Appends two arrays.

+		Immutable
array_cat(left: jsonb[], right: jsonb[]) → jsonb[]

Appends two arrays.

+		Immutable
array_cat(left: oid[], right: oid[]) → oid[]

Appends two arrays.

+		Immutable
array_cat(left: pg_lsn[], right: pg_lsn[]) → pg_lsn[]

Appends two arrays.

+		Immutable
array_cat(left: refcursor[], right: refcursor[]) → refcursor[]

Appends two arrays.

+		Immutable
array_cat(left: timetz[], right: timetz[]) → timetz[]

Appends two arrays.

+		Immutable
array_cat(left: tuple[], right: tuple[]) → tuple[]

Appends two arrays.

+		Immutable
array_cat(left: varbit[], right: varbit[]) → varbit[]

Appends two arrays.

+		Immutable
array_length(input: anyelement[], array_dimension: int) → int

Calculates the length of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_lower(input: anyelement[], array_dimension: int) → int

Calculates the minimum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_position(array: bool[], elem: bool) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bool[], elem: bool, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: bytes[], elem: bytes) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bytes[], elem: bytes, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: date[], elem: date) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: date[], elem: date, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: decimal[], elem: decimal) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: decimal[], elem: decimal, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: float[], elem: float) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: float[], elem: float, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: inet[], elem: inet) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: inet[], elem: inet, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: int[], elem: int) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: int[], elem: int, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: interval[], elem: interval) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: interval[], elem: interval, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: string[], elem: string) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: string[], elem: string, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: time[], elem: time) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: time[], elem: time, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timestamp[], elem: timestamp) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamp[], elem: timestamp, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: uuid[], elem: uuid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: uuid[], elem: uuid, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: anyenum[], elem: anyenum) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: anyenum[], elem: anyenum, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: box2d[], elem: box2d) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: box2d[], elem: box2d, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: geography[], elem: geography) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geography[], elem: geography, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: geometry[], elem: geometry) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geometry[], elem: geometry, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: jsonb[], elem: jsonb) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: jsonb[], elem: jsonb, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: oid[], elem: oid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: oid[], elem: oid, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: refcursor[], elem: refcursor) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: refcursor[], elem: refcursor, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timetz[], elem: timetz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timetz[], elem: timetz, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: tuple[], elem: tuple) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: tuple[], elem: tuple, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: varbit[], elem: varbit) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: varbit[], elem: varbit, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_positions(array: bool[], elem: bool) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: bytes[], elem: bytes) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: date[], elem: date) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: decimal[], elem: decimal) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: float[], elem: float) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: inet[], elem: inet) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: int[], elem: int) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: interval[], elem: interval) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: string[], elem: string) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: time[], elem: time) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamp[], elem: timestamp) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamptz[], elem: timestamptz) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: uuid[], elem: uuid) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: anyenum[], elem: anyenum) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: box2d[], elem: box2d) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geography[], elem: geography) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geometry[], elem: geometry) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: jsonb[], elem: jsonb) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: oid[], elem: oid) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: pg_lsn[], elem: pg_lsn) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: refcursor[], elem: refcursor) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timetz[], elem: timetz) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: tuple[], elem: tuple) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: varbit[], elem: varbit) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_prepend(elem: bool, array: bool[]) → bool[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: bytes, array: bytes[]) → bytes[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: date, array: date[]) → date[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: decimal, array: decimal[]) → decimal[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: float, array: float[]) → float[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: inet, array: inet[]) → inet[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: int, array: int[]) → int[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: interval, array: interval[]) → interval[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: string, array: string[]) → string[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: time, array: time[]) → time[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamp, array: timestamp[]) → timestamp[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamptz, array: timestamptz[]) → timestamptz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: uuid, array: uuid[]) → uuid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: anyenum, array: anyenum[]) → anyenum[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: box2d, array: box2d[]) → box2d[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geography, array: geography[]) → geography[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geometry, array: geometry[]) → geometry[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: jsonb, array: jsonb[]) → jsonb[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: oid, array: oid[]) → oid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: pg_lsn, array: pg_lsn[]) → pg_lsn[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: refcursor, array: refcursor[]) → refcursor[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timetz, array: timetz[]) → timetz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: tuple, array: tuple[]) → tuple[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: varbit, array: varbit[]) → varbit[]

Prepends elem to array, returning the result.

+		Immutable
array_remove(array: bool[], elem: bool) → bool[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: bytes[], elem: bytes) → bytes[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: date[], elem: date) → date[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: decimal[], elem: decimal) → decimal[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: float[], elem: float) → float[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: inet[], elem: inet) → inet[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: int[], elem: int) → int[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: interval[], elem: interval) → interval[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: string[], elem: string) → string[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: time[], elem: time) → time[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamp[], elem: timestamp) → timestamp[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamptz[], elem: timestamptz) → timestamptz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: uuid[], elem: uuid) → uuid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: anyenum[], elem: anyenum) → anyenum[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: box2d[], elem: box2d) → box2d[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geography[], elem: geography) → geography[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geometry[], elem: geometry) → geometry[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: jsonb[], elem: jsonb) → jsonb[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: oid[], elem: oid) → oid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: refcursor[], elem: refcursor) → refcursor[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timetz[], elem: timetz) → timetz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: tuple[], elem: tuple) → tuple[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: varbit[], elem: varbit) → varbit[]

Remove from array all elements equal to elem.

+		Immutable
array_replace(array: bool[], toreplace: bool, replacewith: bool) → bool[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: bytes[], toreplace: bytes, replacewith: bytes) → bytes[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: date[], toreplace: date, replacewith: date) → date[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: decimal[], toreplace: decimal, replacewith: decimal) → decimal[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: float[], toreplace: float, replacewith: float) → float[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: inet[], toreplace: inet, replacewith: inet) → inet[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: int[], toreplace: int, replacewith: int) → int[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: interval[], toreplace: interval, replacewith: interval) → interval[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: string[], toreplace: string, replacewith: string) → string[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: time[], toreplace: time, replacewith: time) → time[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamp[], toreplace: timestamp, replacewith: timestamp) → timestamp[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamptz[], toreplace: timestamptz, replacewith: timestamptz) → timestamptz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: uuid[], toreplace: uuid, replacewith: uuid) → uuid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: anyenum[], toreplace: anyenum, replacewith: anyenum) → anyenum[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: box2d[], toreplace: box2d, replacewith: box2d) → box2d[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geography[], toreplace: geography, replacewith: geography) → geography[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geometry[], toreplace: geometry, replacewith: geometry) → geometry[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: jsonb[], toreplace: jsonb, replacewith: jsonb) → jsonb[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: oid[], toreplace: oid, replacewith: oid) → oid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: pg_lsn[], toreplace: pg_lsn, replacewith: pg_lsn) → pg_lsn[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: refcursor[], toreplace: refcursor, replacewith: refcursor) → refcursor[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timetz[], toreplace: timetz, replacewith: timetz) → timetz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: tuple[], toreplace: tuple, replacewith: tuple) → tuple[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: varbit[], toreplace: varbit, replacewith: varbit) → varbit[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_to_string(input: anyelement[], delim: string) → string

Join an array into a string with a delimiter.

+		Stable
array_to_string(input: anyelement[], delimiter: string, null: string) → string

Join an array into a string with a delimiter, replacing NULLs with a null string.

+		Stable
array_upper(input: anyelement[], array_dimension: int) → int

Calculates the maximum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
cardinality(input: anyelement[]) → int

Calculates the number of elements contained in input

+		Immutable
jsonb_array_to_string_array(input: jsonb) → string[]

Convert a JSONB array into a string array.

+		Immutable
string_to_array(str: string, delimiter: string) → string[]

Split a string into components on a delimiter.

+		Immutable
string_to_array(str: string, delimiter: string, null: string) → string[]

Split a string into components on a delimiter with a specified string to consider NULL.

+		Immutable
+ +### BOOL functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Matches case insensetively unescaped with pattern using escape as an escape token.

+		Immutable
inet_contained_by_or_equals(val: inet, container: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_contains_or_equals(container: inet, val: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_same_family(val: inet, val: inet) → bool

Checks if two IP addresses are of the same IP family.

+		Immutable
like_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
not_ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches case insensetively with pattern using escape as an escape token.

+		Immutable
not_like_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
not_similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
+ +### Comparison functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
greatest(anyelement...) → anyelement

Returns the element with the greatest value.

+		Immutable
least(anyelement...) → anyelement

Returns the element with the lowest value.

+		Immutable
num_nonnulls(anyelement...) → int

Returns the number of nonnull arguments.

+		Immutable
num_nulls(anyelement...) → int

Returns the number of null arguments.

+		Immutable
+ +### Cryptographic functions + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crypt(password: string, salt: string) → string

Generates a hash based on a password and salt. The hash algorithm and number of rounds if applicable are encoded in the salt.

+		Immutable
decrypt(data: bytes, key: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
decrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
digest(data: bytes, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
digest(data: string, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
encrypt(data: bytes, key: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
encrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
gen_random_bytes(count: int) → bytes

Returns count cryptographically strong random bytes. At most 1024 bytes can be extracted at a time.

+		Volatile
gen_salt(type: string) → string

Generates a salt for input into the crypt function using the default number of rounds.

+		Volatile
gen_salt(type: string, iter_count: int) → string

Generates a salt for input into the crypt function using iter_count number of rounds.

+		Volatile
hmac(data: bytes, key: bytes, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
hmac(data: string, key: string, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
+ +### DECIMAL functions + + + + + +
Function → ReturnsDescriptionVolatility
hlc_to_timestamp(hlc: decimal) → timestamptz

Returns a TimestampTZ representation of a CockroachDB HLC in decimal form.

+

Note that a TimestampTZ has less precision than a CockroachDB HLC. It is intended as +a convenience function to display HLCs in a print-friendly form. Use the decimal +value if you rely on the HLC for accuracy.

+		Immutable
+ +### Date and time functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
age(end: timestamptz, begin: timestamptz) → interval

Calculates the interval between begin and end, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use the timestamptz subtraction operator.

+		Immutable
age(val: timestamptz) → interval

Calculates the interval between val and the current time, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use now() - timestamptz.

+		Stable
clock_timestamp() → timestamp

Returns the current system time on one of the cluster nodes.

+		Volatile
clock_timestamp() → timestamptz

Returns the current system time on one of the cluster nodes.

+		Volatile
current_date() → date

Returns the date of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_timestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
date_part(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
date_part(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
date_trunc(element: string, input: date) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: interval) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: time) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero.

+

Compatible elements: hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamp) → timestamp

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamptz) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: timestamptz, timezone: string) → timestamptz

Truncates input to precision element in the specified timezone. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
experimental_follower_read_timestamp() → timestamptz

Same as follower_read_timestamp. This name is deprecated.

+		Volatile
experimental_strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
extract(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
extract(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
extract_duration(element: string, input: interval) → int

Extracts element from input. +Compatible elements: hour, minute, second, millisecond, microsecond. +This is deprecated in favor of extract which supports duration.

+		Immutable
follower_read_timestamp() → timestamptz

Returns a timestamp which is very likely to be safe to perform +against a follower replica.

+

This function is intended to be used with an AS OF SYSTEM TIME clause to perform +historical reads against a time which is recent but sufficiently old for reads +to be performed against the closest replica as opposed to the currently +leaseholder for a given range.

+

Note that this function requires an enterprise license on a CCL distribution to +return a result that is less likely the closest replica. It is otherwise +hardcoded as -4.8s from the statement time, which may not result in reading from the +nearest replica.

+		Volatile
localtimestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
make_date(year: int, month: int, day: int) → date

Create date (formatted according to ISO 8601) from year, month, and day fields (negative years signify BC).

+		Immutable
make_timestamp(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamp

Create timestamp (formatted according to ISO 8601) from year, month, day, hour, minute, and seconds fields (negative years signify BC).

+		Immutable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float, timezone: string) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
now() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
overlaps(s1: date, e1: date, s1: date, e2: date) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: date, e1: interval, s1: date, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: interval, s1: time, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: time, s1: time, e2: time) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: interval, s1: timestamp, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: timestamp, s1: timestamp, e2: timestamp) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamptz, e1: interval, s1: timestamptz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Stable
overlaps(s1: timestamptz, e1: timestamptz, s1: timestamptz, e2: timestamptz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: interval, s1: timetz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: timetz, s1: timetz, e2: timetz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
statement_timestamp() → timestamp

Returns the start time of the current statement.

+		Stable
statement_timestamp() → timestamptz

Returns the start time of the current statement.

+		Stable
strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
timeofday() → string

Returns the current system time on one of the cluster nodes as a string.

+		Stable
timezone(timezone: string, time: time) → timetz

Treat given time without time zone as located in the specified time zone.

+		Stable
timezone(timezone: string, timestamp: timestamp) → timestamptz

Treat given time stamp without time zone as located in the specified time zone.

+		Immutable
timezone(timezone: string, timestamptz: timestamptz) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Immutable
timezone(timezone: string, timestamptz_string: string) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Stable
timezone(timezone: string, timetz: timetz) → timetz

Convert given time with time zone to the new time zone.

+		Stable
to_char(date: date) → string

Convert an date to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(date: date, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_char(interval: interval) → string

Convert an interval to a string assuming the Postgres IntervalStyle.

+		Immutable
to_char(interval: interval, format: string) → string

Convert an interval to a string using the given format.

+		Stable
to_char(timestamp: timestamp) → string

Convert an timestamp to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(timestamp: timestamp, format: string) → string

Convert an timestamp to a string using the given format.

+		Stable
to_char(timestamptz: timestamptz, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_timestamp(timestamp: float) → timestamptz

Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to timestamp with time zone.

+		Immutable
transaction_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
with_max_staleness(max_staleness: interval) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_max_staleness(max_staleness: interval, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
+ +### Enum functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
enum_first(val: anyenum) → anyenum

Returns the first value of the input enum type.

+		Stable
enum_last(val: anyenum) → anyenum

Returns the last value of the input enum type.

+		Stable
enum_range(lower: anyenum, upper: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array between the two arguments (inclusive).

+		Stable
enum_range(val: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array.

+		Stable
+ +### FLOAT functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abs(val: decimal) → decimal

Calculates the absolute value of val.

+		Immutable
abs(val: float) → float

Calculates the absolute value of val.

+		Immutable
abs(val: int) → int

Calculates the absolute value of val.

+		Immutable
acos(val: float) → float

Calculates the inverse cosine of val.

+		Immutable
acosd(val: float) → float

Calculates the inverse cosine of val with the result in degrees

+		Immutable
acosh(val: float) → float

Calculates the inverse hyperbolic cosine of val.

+		Immutable
asin(val: float) → float

Calculates the inverse sine of val.

+		Immutable
asind(val: float) → float

Calculates the inverse sine of val with the result in degrees.

+		Immutable
asinh(val: float) → float

Calculates the inverse hyperbolic sine of val.

+		Immutable
atan(val: float) → float

Calculates the inverse tangent of val.

+		Immutable
atan2(x: float, y: float) → float

Calculates the inverse tangent of x/y.

+		Immutable
atan2d(x: float, y: float) → float

Calculates the inverse tangent of x/y with the result in degrees

+		Immutable
atand(val: float) → float

Calculates the inverse tangent of val with the result in degrees.

+		Immutable
atanh(val: float) → float

Calculates the inverse hyperbolic tangent of val.

+		Immutable
cbrt(val: decimal) → decimal

Calculates the cube root (∛) of val.

+		Immutable
cbrt(val: float) → float

Calculates the cube root (∛) of val.

+		Immutable
ceil(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
cos(val: float) → float

Calculates the cosine of val.

+		Immutable
cosd(val: float) → float

Calculates the cosine of val where val is in degrees.

+		Immutable
cosh(val: float) → float

Calculates the hyperbolic cosine of val.

+		Immutable
cot(val: float) → float

Calculates the cotangent of val.

+		Immutable
cotd(val: float) → float

Calculates the cotangent of val where val is in degrees.

+		Immutable
degrees(val: float) → float

Converts val as a radian value to a degree value.

+		Immutable
div(x: decimal, y: decimal) → decimal

Calculates the integer quotient of x/y.

+		Immutable
div(x: float, y: float) → float

Calculates the integer quotient of x/y.

+		Immutable
div(x: int, y: int) → int

Calculates the integer quotient of x/y.

+		Immutable
exp(val: decimal) → decimal

Calculates e ^ val.

+		Immutable
exp(val: float) → float

Calculates e ^ val.

+		Immutable
floor(val: decimal) → decimal

Calculates the largest integer not greater than val.

+		Immutable
floor(val: float) → float

Calculates the largest integer not greater than val.

+		Immutable
floor(val: int) → float

Calculates the largest integer not greater than val.

+		Immutable
isnan(val: decimal) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
isnan(val: float) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
ln(val: decimal) → decimal

Calculates the natural log of val.

+		Immutable
ln(val: float) → float

Calculates the natural log of val.

+		Immutable
log(b: decimal, x: decimal) → decimal

Calculates the base b log of val.

+		Immutable
log(b: float, x: float) → float

Calculates the base b log of val.

+		Immutable
log(val: decimal) → decimal

Calculates the base 10 log of val.

+		Immutable
log(val: float) → float

Calculates the base 10 log of val.

+		Immutable
mod(x: decimal, y: decimal) → decimal

Calculates x%y.

+		Immutable
mod(x: float, y: float) → float

Calculates x%y.

+		Immutable
mod(x: int, y: int) → int

Calculates x%y.

+		Immutable
pi() → float

Returns the value for pi (3.141592653589793).

+		Immutable
pow(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
pow(x: float, y: float) → float

Calculates x^y.

+		Immutable
pow(x: int, y: int) → int

Calculates x^y.

+		Immutable
power(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
power(x: float, y: float) → float

Calculates x^y.

+		Immutable
power(x: int, y: int) → int

Calculates x^y.

+		Immutable
radians(val: float) → float

Converts val as a degree value to a radians value.

+		Immutable
random() → float

Returns a random floating-point number between 0 (inclusive) and 1 (exclusive). Note that the value contains at most 53 bits of randomness.

+		Volatile
round(input: decimal, decimal_accuracy: int) → decimal

Keeps decimal_accuracy number of figures to the right of the zero position in input using half away from zero rounding. If decimal_accuracy is not in the range -2^31…(2^31-1), the results are undefined.

+		Immutable
round(input: float, decimal_accuracy: int) → float

Keeps decimal_accuracy number of figures to the right of the zero position in input using half to even (banker’s) rounding.

+		Immutable
round(val: decimal) → decimal

Rounds val to the nearest integer, half away from zero: round(+/-2.4) = +/-2, round(+/-2.5) = +/-3.

+		Immutable
round(val: float) → float

Rounds val to the nearest integer using half to even (banker’s) rounding.

+		Immutable
setseed(seed: float) → void

Sets the seed for subsequent random() calls in this session (value between -1.0 and 1.0, inclusive). There are no guarantees as to how this affects the seed of random() calls that appear in the same query as setseed().

+		Volatile
sign(val: decimal) → decimal

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: float) → float

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: int) → int

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sin(val: float) → float

Calculates the sine of val.

+		Immutable
sind(val: float) → float

Calculates the sine of val where val is in degrees.

+		Immutable
sinh(val: float) → float

Calculates the hyperbolic sine of val.

+		Immutable
sqrt(val: decimal) → decimal

Calculates the square root of val.

+		Immutable
sqrt(val: float) → float

Calculates the square root of val.

+		Immutable
tan(val: float) → float

Calculates the tangent of val.

+		Immutable
tand(val: float) → float

Calculates the tangent of val where val is in degrees.

+		Immutable
tanh(val: float) → float

Calculates the hyperbolic tangent of val.

+		Immutable
trunc(val: decimal) → decimal

Truncates the decimal values of val.

+		Immutable
trunc(val: decimal, scale: int) → decimal

Truncate val to scale decimal places

+		Immutable
trunc(val: float) → float

Truncates the decimal values of val.

+		Immutable
+ +### Full Text Search functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
phraseto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The <-> operator is inserted between each token in the input.

+		Immutable
phraseto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The <-> operator is inserted between each token in the input.

+		Stable
plainto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The & operator is inserted between each token in the input.

+		Immutable
plainto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The & operator is inserted between each token in the input.

+		Stable
to_tsquery(config: string, text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the specified configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Immutable
to_tsquery(text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the default configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Stable
to_tsvector(config: string, text: string) → tsvector

Converts text to a tsvector, normalizing words according to the specified configuration. Position information is included in the result.

+		Immutable
to_tsvector(text: string) → tsvector

Converts text to a tsvector, normalizing words according to the default configuration. Position information is included in the result.

+		Stable
ts_parse(parser_name: string, document: string) → tuple{int AS tokid, string AS token}

ts_parse parses the given document and returns a series of records, one for each token produced by parsing. Each record includes a tokid showing the assigned token type and a token which is the text of the token.

+		Stable
ts_rank(vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
+ +### Fuzzy String Matching functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
levenshtein(source: string, target: string) → int

Calculates the Levenshtein distance between two strings. Maximum input length is 255 characters.

+		Immutable
levenshtein(source: string, target: string, ins_cost: int, del_cost: int, sub_cost: int) → int

Calculates the Levenshtein distance between two strings. The cost parameters specify how much to charge for each edit operation. Maximum input length is 255 characters.

+		Immutable
metaphone(source: string, max_output_length: int) → string

Convert a string to its Metaphone code. Maximum input length is 255 characters

+		Immutable
soundex(source: string) → string

Convert a string to its Soundex code.

+		Immutable
+ +### ID generation functions + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
experimental_uuid_v4() → bytes

Returns a UUID.

+		Volatile
gen_random_ulid() → uuid

Generates a random ULID and returns it as a value of UUID type.

+		Volatile
gen_random_uuid() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
unique_rowid() → int

Returns a unique ID used by CockroachDB to generate unique row IDs if a Primary Key isn’t defined for the table. The value is a combination of the insert timestamp and the ID of the node executing the statement, which guarantees this combination is globally unique. However, there can be gaps and the order is not completely guaranteed.

+		Volatile
unordered_unique_rowid() → int

Returns a unique ID. The value is a combination of the insert timestamp (bit-reversed) and the ID of the node executing the statement, which guarantees this combination is globally unique. The way it is generated is statistically likely to not have any ordering relative to previously generated values.

+		Volatile
uuid_generate_v1() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. To avoid exposing the server’s real MAC address, this uses a random MAC address and a timestamp. Essentially, this is an alias for uuid_generate_v1mc.

+		Volatile
uuid_generate_v1mc() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. This uses a random MAC address and a timestamp.

+		Volatile
uuid_generate_v3(namespace: uuid, name: string) → uuid

Generates a version 3 UUID in the given namespace using the specified input name, with md5 as the hashing method. The namespace should be one of the special constants produced by the uuid_ns_*() functions.

+		Immutable
uuid_generate_v4() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
uuid_generate_v5(namespace: uuid, name: string) → uuid

Generates a version 5 UUID in the given namespace using the specified input name. This is similar to a version 3 UUID, except it uses SHA-1 for hashing.

+		Immutable
uuid_nil() → uuid

Returns a nil UUID constant.

+		Immutable
uuid_ns_dns() → uuid

Returns a constant designating the DNS namespace for UUIDs.

+		Immutable
uuid_ns_oid() → uuid

Returns a constant designating the ISO object identifier (OID) namespace for UUIDs. These are unrelated to the OID type used internally in the database.

+		Immutable
uuid_ns_url() → uuid

Returns a constant designating the URL namespace for UUIDs.

+		Immutable
uuid_ns_x500() → uuid

Returns a constant designating the X.500 distinguished name (DN) namespace for UUIDs.

+		Immutable
uuid_v4() → bytes

Returns a UUID.

+		Volatile
+ +### INET functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abbrev(val: inet) → string

Converts the combined IP address and prefix length to an abbreviated display format as text.For INET types, this will omit the prefix length if it’s not the default (32 or IPv4, 128 for IPv6)

+

For example, abbrev('192.168.1.2/24') returns '192.168.1.2/24'

+		Immutable
broadcast(val: inet) → inet

Gets the broadcast address for the network address represented by the value.

+

For example, broadcast('192.168.1.2/24') returns '192.168.1.255/24'

+		Immutable
family(val: inet) → int

Extracts the IP family of the value; 4 for IPv4, 6 for IPv6.

+

For example, family('::1') returns 6

+		Immutable
host(val: inet) → string

Extracts the address part of the combined address/prefixlen value as text.

+

For example, host('192.168.1.2/16') returns '192.168.1.2'

+		Immutable
hostmask(val: inet) → inet

Creates an IP host mask corresponding to the prefix length in the value.

+

For example, hostmask('192.168.1.2/16') returns '0.0.255.255'

+		Immutable
masklen(val: inet) → int

Retrieves the prefix length stored in the value.

+

For example, masklen('192.168.1.2/16') returns 16

+		Immutable
netmask(val: inet) → inet

Creates an IP network mask corresponding to the prefix length in the value.

+

For example, netmask('192.168.1.2/16') returns '255.255.0.0'

+		Immutable
set_masklen(val: inet, prefixlen: int) → inet

Sets the prefix length of val to prefixlen.

+

For example, set_masklen('192.168.1.2', 16) returns '192.168.1.2/16'.

+		Immutable
+ +### INT functions + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crc32c(bytes...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32c(string...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32ieee(bytes...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
crc32ieee(string...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
fnv32(bytes...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32(string...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32a(bytes...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv32a(string...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64(bytes...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64(string...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64a(bytes...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64a(string...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
width_bucket(operand: decimal, b1: decimal, b2: decimal, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2.

+		Immutable
width_bucket(operand: int, b1: int, b2: int, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2.

+		Immutable
width_bucket(operand: anyelement, thresholds: anyelement[]) → int

return the bucket number to which operand would be assigned given an array listing the lower bounds of the buckets; returns 0 for an input less than the first lower bound; the thresholds array must be sorted, smallest first, or unexpected results will be obtained

+		Immutable
+ +### JSONB functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_to_json(array: anyelement[]) → jsonb

Returns the array as JSON or JSONB.

+		Stable
array_to_json(array: anyelement[], pretty_bool: bool) → jsonb

Returns the array as JSON or JSONB.

+		Stable
json_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
json_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
json_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
json_build_array(anyelement...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
json_build_object(anyelement...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
json_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
json_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
json_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
json_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
json_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
json_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
json_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
json_remove_path(val: jsonb, path: string[]) → jsonb

Remove the specified path from the JSON object.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
json_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
json_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
json_valid(string: string) → bool

Returns whether the given string is a valid JSON or not

+		Immutable
jsonb_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
jsonb_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
jsonb_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
jsonb_build_array(anyelement...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
jsonb_build_object(anyelement...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
jsonb_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
jsonb_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
jsonb_exists_any(json: jsonb, array: string[]) → bool

Returns whether any of the strings in the text array exist as top-level keys or array elements

+		Immutable
jsonb_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments. new_val will be inserted before path target.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb, insert_after: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If insert_after is true (default is false), new_val will be inserted after path target.

+		Immutable
jsonb_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
jsonb_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
jsonb_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
jsonb_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
jsonb_pretty(val: jsonb) → string

Returns the given JSON value as a STRING indented and with newlines.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
jsonb_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
jsonb_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
row_to_json(row: tuple) → jsonb

Returns the row as a JSON object.

+		Stable
to_json(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
to_jsonb(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
+ +### Multi-region functions + + + + + + + +
Function → ReturnsDescriptionVolatility
default_to_database_primary_region(val: string) → string

Returns the given region if the region has been added to the current database. +Otherwise, this will return the primary region of the current database. +This will error if the current database is not a multi-region database.

+		Stable
gateway_region() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
rehome_row() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
+ +### PGVector functions + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cosine_distance(v1: vector, v2: vector) → float

Returns the cosine distance between the two vectors.

+		Immutable
inner_product(v1: vector, v2: vector) → float

Returns the inner product between the two vectors.

+		Immutable
l1_distance(v1: vector, v2: vector) → float

Returns the Manhattan distance between the two vectors.

+		Immutable
l2_distance(v1: vector, v2: vector) → float

Returns the Euclidean distance between the two vectors.

+		Immutable
vector_dims(vector: vector) → int

Returns the number of the dimensions in the vector.

+		Immutable
vector_norm(vector: vector) → float

Returns the Euclidean norm of the vector.

+		Immutable
+ +### STRING[] functions + + + + + + +
Function → ReturnsDescriptionVolatility
regexp_split_to_array(string: string, pattern: string) → string[]

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_array(string: string, pattern: string, flags: string) → string[]

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
+ +### Sequence functions + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
currval(sequence_name: string) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
currval(sequence_name: regclass) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
lastval() → int

Return value most recently obtained with nextval in this session.

+		Volatile
nextval(sequence_name: string) → int

Advances the given sequence and returns its new value.

+		Volatile
nextval(sequence_name: regclass) → int

Advances the given sequence and returns its new value.

+		Volatile
setval(sequence_name: string, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: string, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
setval(sequence_name: regclass, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: regclass, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
+ +### Set-returning functions + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
aclexplode(aclitems: string[]) → tuple{oid AS grantor, oid AS grantee, string AS privilege_type, bool AS is_grantable}

Produces a virtual table containing aclitem stuff (returns no rows as this feature is unsupported in CockroachDB)

+		Stable
generate_series(start: int, end: int) → int

Produces a virtual table containing the integer values from start to end, inclusive.

+		Immutable
generate_series(start: int, end: int, step: int) → int

Produces a virtual table containing the integer values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamp, end: timestamp, step: interval) → timestamp

Produces a virtual table containing the timestamp values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamptz, end: timestamptz, step: interval) → timestamptz

Produces a virtual table containing the timestampTZ values from start to end, inclusive, by increment of step.

+		Immutable
generate_subscripts(array: anyelement[]) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int, reverse: bool) → int

Returns a series comprising the given array’s subscripts.

+

When reverse is true, the series is returned in reverse order.

+		Immutable
information_schema._pg_expandarray(input: anyelement[]) → tuple{anyelement AS x, int AS n}

Returns the input array as a set of rows with an index

+		Immutable
json_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
json_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
json_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
jsonb_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
jsonb_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
jsonb_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
pg_get_keywords() → tuple{string AS word, string AS catcode, string AS catdesc}

Produces a virtual table containing the keywords known to the SQL parser.

+		Immutable
pg_options_to_table(options: string[]) → tuple{string AS option_name, string AS option_value}

Converts the options array format to a table.

+		Stable
regexp_split_to_table(string: string, pattern: string) → string

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_table(string: string, pattern: string, flags: string) → string

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
unnest(anyelement[], anyelement[], anyelement[]...) → tuple{anyelement AS unnest, anyelement AS unnest, anyelement AS unnest}

Returns the input arrays as a set of rows

+		Immutable
unnest(input: anyelement[]) → anyelement

Returns the input array as a set of rows

+		Immutable
workload_index_recs() → string

Returns set of index recommendations

+		Immutable
workload_index_recs(timestamptz: timestamptz) → string

Returns set of index recommendations

+		Immutable
+ +### Spatial functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
_st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
geometrytype(geometry: geometry) → string

Returns the type of geometry as a string.

+

This function utilizes the GEOS module.

+		Immutable
geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
postgis_addbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_dropbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_extensions_upgrade() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_full_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_geos_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_getbbox(geometry: geometry) → box2d

Returns a box2d encapsulating the given Geometry.

+		Immutable
postgis_hasbbox(geometry: geometry) → bool

Returns whether a given Geometry has a bounding box. False for points and empty geometries; always true otherwise.

+		Immutable
postgis_lib_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_lib_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_liblwgeom_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_libxml_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_proj_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_installed() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_released() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_wagyu_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
st_addmeasure(geometry: geometry, start: float, end: float) → geometry

Returns a copy of a LineString or MultiLineString with measure coordinates linearly interpolated between the specified start and end values. Any existing M coordinates will be overwritten.

+		Immutable
st_addpoint(line_string: geometry, point: geometry) → geometry

Adds a Point to the end of a LineString.

+		Immutable
st_addpoint(line_string: geometry, point: geometry, index: int) → geometry

Adds a Point to a LineString at the given 0-based index (-1 to append).

+		Immutable
st_affine(geometry: geometry, a: float, b: float, c: float, d: float, e: float, f: float, g: float, h: float, i: float, x_off: float, y_off: float, z_off: float) → geometry

Applies a 3D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b c x_off \ / x
+| d e f y_off | | y | +| g h i z_off | | z | +\ 0 0 0 1 / \ 0 /

+		Immutable
st_affine(geometry: geometry, a: float, b: float, d: float, e: float, x_off: float, y_off: float) → geometry

Applies a 2D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b x_off \ / x
+| d e y_off | | y | +\ 0 0 1 / \ 0 /

+		Immutable
st_angle(line1: geometry, line2: geometry) → float

Returns the clockwise angle between two LINESTRING geometries, treating them as vectors between their start- and endpoints. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry) → float

Returns the clockwise angle between the vectors formed by point2,point1 and point2,point3. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry, point4: geometry) → float

Returns the clockwise angle between the vectors formed by point1,point2 and point3,point4. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_area(geography: geography) → float

Returns the area of the given geography in meters^2. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geography: geography, use_spheroid: bool) → float

Returns the area of the given geography in meters^2.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_area(geometry_str: string) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_area2d(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_asbinary(geography: geography) → bytes

Returns the WKB representation of a given Geography.

+		Immutable
st_asbinary(geography: geography, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asbinary(geometry: geometry) → bytes

Returns the WKB representation of a given Geometry.

+		Immutable
st_asbinary(geometry: geometry, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asencodedpolyline(geometry: geometry) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Preserves 5 decimal places.

+		Immutable
st_asencodedpolyline(geometry: geometry, precision: int4) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+		Immutable
st_asewkb(geography: geography) → bytes

Returns the EWKB representation of a given Geography.

+		Immutable
st_asewkb(geometry: geometry) → bytes

Returns the EWKB representation of a given Geometry.

+		Immutable
st_asewkt(geography: geography) → string

Returns the EWKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_asewkt(geography: geography, max_decimal_digits: int) → string

Returns the EWKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry: geometry) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_asewkt(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry_str: string) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asewkt(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geography: geography) → string

Returns the GeoJSON representation of a given Geography. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option (default for Geography)
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326
    • +
+		Immutable
st_asgeojson(geometry: geometry) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+		Immutable
st_asgeojson(geometry_str: string) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(row: tuple) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(row: tuple, geo_column: string) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. Coordinates have a maximum of 9 decimal digits.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int, pretty: bool) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value. Output will be pretty printed in JSON if pretty is true.

+		Stable
st_ashexewkb(geography: geography) → string

Returns the EWKB representation in hex of a given Geography.

+		Immutable
st_ashexewkb(geography: geography, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexewkb(geometry: geometry) → string

Returns the EWKB representation in hex of a given Geometry.

+		Immutable
st_ashexewkb(geometry: geometry, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexwkb(geography: geography) → string

Returns the WKB representation in hex of a given Geography.

+		Immutable
st_ashexwkb(geometry: geometry) → string

Returns the WKB representation in hex of a given Geometry.

+		Immutable
st_askml(geography: geography) → string

Returns the KML representation of a given Geography.

+		Immutable
st_askml(geometry: geometry) → string

Returns the KML representation of a given Geometry.

+		Immutable
st_askml(geometry_str: string) → string

Returns the KML representation of a given Geometry.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping. +Uses 4096 as the tile extent size in tile coordinate space.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int, clip: bool) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds if required.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry can be transformed, and clipped if required.

+		Immutable
st_astext(geography: geography) → string

Returns the WKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_astext(geography: geography, max_decimal_digits: int) → string

Returns the WKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry: geometry) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_astext(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry_str: string) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astext(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int, precision_m: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_azimuth(geography_a: geography, geography_b: geography) → float

Returns the azimuth in radians of the segment defined by the given point geographies, or NULL if the two points are coincident. It is solved using the Inverse geodesic problem.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_azimuth(geometry_a: geometry, geometry_b: geometry) → float

Returns the azimuth in radians of the segment defined by the given point geometries, or NULL if the two points are coincident.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+		Immutable
st_bdpolyfromtext(str: string, srid: int) → geometry

Returns a Polygon from multilinestring WKT with a SRID. If the input is not a multilinestring an error will be thrown.

+		Immutable
st_boundary(geometry: geometry) → geometry

Returns the closure of the combinatorial boundary of this Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_box2dfromgeohash(geohash: string) → box2d

Return a Box2D from a GeoHash string with max precision.

+		Immutable
st_box2dfromgeohash(geohash: string, precision: int) → box2d

Return a Box2D from a GeoHash string with supplied precision.

+		Immutable
st_buffer(geography: geography, distance: float) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, buffer_style_params: string) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, quad_segs: int) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geometry: geometry, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry_str: string, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_centroid(geography: geography) → geography

Returns the centroid of given geography. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geography: geography, use_spheroid: bool) → geography

Returns the centroid of given geography.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geometry: geometry) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_centroid(geometry_str: string) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_clipbybox2d(geometry: geometry, box2d: box2d) → geometry

Clips the geometry to conform to the bounding box specified by box2d.

+		Immutable
st_closestpoint(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the 2-dimensional point on geometry_a that is closest to geometry_b. This is the first point of the shortest line.

+		Immutable
st_collectionextract(geometry: geometry, type: int) → geometry

Given a collection, returns a multitype consisting only of elements of the specified type. If there are no elements of the given type, an EMPTY geometry is returned. Types are specified as 1=POINT, 2=LINESTRING, 3=POLYGON - other types are not supported.

+		Immutable
st_collectionhomogenize(geometry: geometry) → geometry

Returns the “simplest” representation of a collection’s contents. Collections of a single type will be returned as an appopriate multitype, or a singleton if it only contains a single geometry.

+		Immutable
st_combinebbox(box2d: box2d, geometry: geometry) → box2d

Combines the current bounding box with the bounding box of the Geometry.

+		Immutable
st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_convexhull(geometry: geometry) → geometry

Returns a geometry that represents the Convex Hull of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_coorddim(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_difference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the difference of two Geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_dimension(geometry: geometry) → int

Returns the number of topological dimensions of a given Geometry.

+		Immutable
st_disjoint(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a does not overlap, touch or is within geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_distance(geography_a: geography, geography_b: geography) → float

Returns the distance in meters between geography_a and geography_b. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geography_a: geography, geography_b: geography, use_spheroid: bool) → float

Returns the distance in meters between geography_a and geography_b.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance between the given geometries.

+		Immutable
st_distance(geometry_a_str: string, geometry_b_str: string) → float

Returns the distance between the given geometries.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_distancesphere(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_distancespheroid(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a spheroid.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_endpoint(geometry: geometry) → geometry

Returns the last point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_envelope(box2d: box2d) → geometry

Returns a bounding geometry for the given box.

+		Immutable
st_envelope(geometry: geometry) → geometry

Returns a bounding envelope for the given geometry.

+

For geometries which have a POINT or LINESTRING bounding box (i.e. is a single point +or a horizontal or vertical line), a POINT or LINESTRING is returned. Otherwise, the +returned POLYGON will be ordered Bottom Left, Top Left, Top Right, Bottom Right, +Bottom Left.

+		Immutable
st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string, parent_only: bool) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+

The parent_only boolean is always ignored.

+		Stable
st_estimatedextent(table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_expand(box2d: box2d, delta: float) → box2d

Extends the box2d by delta units across all dimensions.

+		Immutable
st_expand(box2d: box2d, delta_x: float, delta_y: float) → box2d

Extends the box2d by delta_x units in the x dimension and delta_y units in the y dimension.

+		Immutable
st_expand(geometry: geometry, delta: float) → geometry

Extends the bounding box represented by the geometry by delta units across all dimensions, returning a Polygon representing the new bounding box.

+		Immutable
st_expand(geometry: geometry, delta_x: float, delta_y: float) → geometry

Extends the bounding box represented by the geometry by delta_x units in the x dimension and delta_y units in the y dimension, returning a Polygon representing the new bounding box.

+		Immutable
st_exteriorring(geometry: geometry) → geometry

Returns the exterior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon.

+		Immutable
st_flipcoordinates(geometry: geometry) → geometry

Returns a new geometry with the X and Y axes flipped.

+		Immutable
st_force2d(geometry: geometry) → geometry

Returns a Geometry that is forced into XY layout with any Z or M dimensions discarded.

+		Immutable
st_force3d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to 0. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry, defaultM: float) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to the specified default M value. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force4d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZM layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float, defaultM: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified Z value. If a M coordinate doesn’t exist, it will be set to the specified M value.

+		Immutable
st_forcecollection(geometry: geometry) → geometry

Converts the geometry into a GeometryCollection.

+		Immutable
st_forcepolygonccw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_forcepolygoncw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Frechet distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Frechet distance between the given geometries, with the given segment densification (range 0.0-1.0, -1 to disable).

+

Smaller densify_frac gives a more accurate Fréchet distance. However, the computation time and memory usage increases with the square of the number of subsegments.

+

This function utilizes the GEOS module.

+		Immutable
st_generatepoints(geometry: geometry, npoints: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. Uses system time as a seed. +The requested number of points must be not larger than 65336.

+		Volatile
st_generatepoints(geometry: geometry, npoints: int4, seed: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. +The requested number of points must be not larger than 65336.

+		Immutable
st_geogfromewkb(val: bytes) → geography

Returns the Geography from an EWKB representation.

+		Immutable
st_geogfromewkt(val: string) → geography

Returns the Geography from an EWKT representation.

+		Immutable
st_geogfromgeojson(val: string) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromgeojson(val: jsonb) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geogfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geogfromwkb(bytes: bytes, srid: int) → geography

Returns the Geography from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geogfromwkb(val: bytes) → geography

Returns the Geography from a WKB (or EWKB) representation.

+		Immutable
st_geographyfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geographyfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geohash(geography: geography) → string

Returns a GeoHash representation of the geeographywith full precision if a point is provided, or with variable precision based on the size of the feature.

+		Immutable
st_geohash(geography: geography, precision: int) → string

Returns a GeoHash representation of the geography with the supplied precision.

+		Immutable
st_geohash(geometry: geometry) → string

Returns a GeoHash representation of the geometry with full precision if a point is provided, or with variable precision based on the size of the feature. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geohash(geometry: geometry, precision: int) → string

Returns a GeoHash representation of the geometry with the supplied precision. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geomcollfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomcollfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geometryfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geometryfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geometryn(geometry: geometry, n: int) → geometry

Returns the n-th Geometry (1-indexed). Returns NULL if out of bounds.

+		Immutable
st_geometrytype(geometry: geometry) → string

Returns the type of geometry as a string prefixed with ST_.

+

This function utilizes the GEOS module.

+		Immutable
st_geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
st_geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
st_geomfromgeohash(geohash: string) → geometry

Return a POLYGON Geometry from a GeoHash string with max precision.

+		Immutable
st_geomfromgeohash(geohash: string, precision: int) → geometry

Return a POLYGON Geometry from a GeoHash string with supplied precision.

+		Immutable
st_geomfromgeojson(val: string) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromgeojson(val: jsonb) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geomfromwkb(bytes: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geomfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_hasarc(geometry: geometry) → bool

Returns whether there is a CIRCULARSTRING in the geometry.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Hausdorff distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Hausdorff distance between the given geometries, with the given segment densification (range 0.0-1.0).

+

This function utilizes the GEOS module.

+		Immutable
st_interiorringn(geometry: geometry, n: int) → geometry

Returns the n-th (1-indexed) interior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon, or the ring does not exist.

+		Immutable
st_intersection(geography_a: geography, geography_b: geography) → geography

Returns the point intersections of the given geographies.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a_str: string, geometry_b_str: string) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_isclosed(geometry: geometry) → bool

Returns whether the geometry is closed as defined by whether the start and end points are coincident. Points are considered closed, empty geometries are not. For collections and multi-types, all members must be closed, as must all polygon rings.

+		Immutable
st_iscollection(geometry: geometry) → bool

Returns whether the geometry is of a collection type (including multi-types).

+		Immutable
st_isempty(geometry: geometry) → bool

Returns whether the geometry is empty.

+		Immutable
st_ispolygonccw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are considered counter-clockwise.

+		Immutable
st_ispolygoncw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are considered clockwise.

+		Immutable
st_isring(geometry: geometry) → bool

Returns whether the geometry is a single linestring that is closed and simple, as defined by ST_IsClosed and ST_IsSimple.

+

This function utilizes the GEOS module.

+		Immutable
st_issimple(geometry: geometry) → bool

Returns true if the geometry has no anomalous geometric points, e.g. that it intersects with or lies tangent to itself.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry) → bool

Returns whether the geometry is valid as defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry, flags: int) → bool

Returns whether the geometry is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry) → string

Returns a string containing the reason the geometry is invalid along with the point of interest, or “Valid Geometry” if it is valid. Validity is defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry, flags: int) → string

Returns the reason the geometry is invalid or “Valid Geometry” if it is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidtrajectory(geometry: geometry) → bool

Returns whether the geometry encodes a valid trajectory.

+

Note the geometry must be a LineString with M coordinates.

+		Immutable
st_length(geography: geography) → float

Returns the length of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geography: geography, use_spheroid: bool) → float

Returns the length of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_length(geometry_str: string) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_length2d(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_linecrossingdirection(linestring_a: geometry, linestring_b: geometry) → int

Returns an interger value defining behavior of crossing of lines: +0: lines do not cross, +-1: linestring_b crosses linestring_a from right to left, +1: linestring_b crosses linestring_a from left to right, +-2: linestring_b crosses linestring_a multiple times from right to left, +2: linestring_b crosses linestring_a multiple times from left to right, +-3: linestring_b crosses linestring_a multiple times from left to left, +3: linestring_b crosses linestring_a multiple times from right to right.

+

Note that the top vertex of the segment touching another line does not count as a crossing, but the bottom vertex of segment touching another line is considered a crossing.

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string) → geometry

Creates a LineString from an Encoded Polyline string.

+

Returns valid results only if the polyline was encoded with 5 decimal places.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string, precision: int4) → geometry

Creates a LineString from an Encoded Polyline string.

+

Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefrommultipoint(geometry: geometry) → geometry

Creates a LineString from a MultiPoint geometry.

+		Immutable
st_linefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_lineinterpolatepoint(geometry: geometry, fraction: float) → geometry

Returns a point along the given LineString which is at given fraction of LineString’s total length.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float, repeat: bool) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length. If repeat is false (default true) then it returns first point.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_linelocatepoint(line: geometry, point: geometry) → float

Returns a float between 0 and 1 representing the location of the closest point on LineString to the given Point, as a fraction of total 2d line length.

+		Immutable
st_linemerge(geometry: geometry) → geometry

Returns a LineString or MultiLineString by joining together constituents of a MultiLineString with matching endpoints. If the input is not a MultiLineString or LineString, an empty GeometryCollection is returned.

+

This function utilizes the GEOS module.

+		Immutable
st_linestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: decimal, end_fraction: decimal) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: float, end_fraction: float) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_longestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the max distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the maximum distance between the geometry’s vertexes. The function will return the longest line that was discovered first when comparing maximum distances if more than one is found.

+		Immutable
st_m(geometry: geometry) → float

Returns the M coordinate of a geometry if it is a Point.

+		Immutable
st_makebox2d(geometry_a: geometry, geometry_b: geometry) → box2d

Creates a box2d from two points. Errors if arguments are not two non-empty points.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with SRID 0.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float, srid: int) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with the given SRID.

+		Immutable
st_makepoint(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float) → geometry

Returns a new Point with the given X, Y, and Z coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float, m: float) → geometry

Returns a new Point with the given X, Y, Z, and M coordinates.

+		Immutable
st_makepointm(x: float, y: float, m: float) → geometry

Returns a new Point with the given X, Y, and M coordinates.

+		Immutable
st_makepolygon(geometry: geometry) → geometry

Returns a new Polygon with the given outer LineString.

+		Immutable
st_makepolygon(outer: geometry, interior: anyelement[]) → geometry

Returns a new Polygon with the given outer LineString and interior (hole) LineString(s).

+		Immutable
st_makevalid(geometry: geometry) → geometry

Returns a valid form of the given geometry according to the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_maxdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the maximum distance across every pair of points comprising the given geometries. Note if the geometries are the same, it will return the maximum distance between the geometry’s vertexes.

+		Immutable
st_memsize(geometry: geometry) → int

Returns the amount of memory space (in bytes) the geometry takes.

+		Immutable
st_minimumboundingcircle(geometry: geometry) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingcircle(geometry: geometry, num_segs: int) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingradius(geometry: geometry) → tuple{geometry AS center, float AS radius}

Returns a record containing the center point and radius of the smallest circle that can fully contains the given geometry.

+		Immutable
st_minimumclearance(geometry: geometry) → float

Returns the minimum distance a vertex can move before producing an invalid geometry. Returns Infinity if no minimum clearance can be found (e.g. for a single point).

+		Immutable
st_minimumclearanceline(geometry: geometry) → geometry

Returns a LINESTRING spanning the minimum distance a vertex can move before producing an invalid geometry. If no minimum clearance can be found (e.g. for a single point), an empty LINESTRING is returned.

+		Immutable
st_mlinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mlinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mpointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multi(geometry: geometry) → geometry

Returns the geometry as a new multi-geometry, e.g converts a POINT to a MULTIPOINT. If the input is already a multitype or collection, it is returned as is.

+		Immutable
st_multilinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multipointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_ndims(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_node(geometry: geometry) → geometry

Adds a node on a geometry for each intersection. Resulting geometry is always a MultiLineString.

+		Immutable
st_normalize(geometry: geometry) → geometry

Returns the geometry in its normalized form.

+

This function utilizes the GEOS module.

+		Immutable
st_npoints(geometry: geometry) → int

Returns the number of points in a given Geometry. Works for any shape type.

+		Immutable
st_nrings(geometry: geometry) → int

Returns the number of rings in a Polygon Geometry. Returns 0 if the shape is not a Polygon.

+		Immutable
st_numgeometries(geometry: geometry) → int

Returns the number of shapes inside a given Geometry.

+		Immutable
st_numinteriorring(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numinteriorrings(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numpoints(geometry: geometry) → int

Returns the number of points in a LineString. Returns NULL if the Geometry is not a LineString.

+		Immutable
st_orderingequals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is exactly equal to geometry_b, having all coordinates in the same order, as well as the same type, SRID, bounding box, and so on.

+		Immutable
st_orientedenvelope(geometry: geometry) → geometry

Returns a minimum rotated rectangle enclosing a geometry. +Note that more than one minimum rotated rectangle may exist. +May return a Point or LineString in the case of degenerate inputs.

+		Immutable
st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_perimeter(geography: geography) → float

Returns the perimeter of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geography: geography, use_spheroid: bool) → float

Returns the perimeter of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_perimeter2d(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_point(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_pointfromgeohash(geohash: string) → geometry

Return a POINT Geometry from a GeoHash string with max precision.

+		Immutable
st_pointfromgeohash(geohash: string, precision: int) → geometry

Return a POINT Geometry from a GeoHash string with supplied precision.

+		Immutable
st_pointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Point, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_pointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointinsidecircle(geometry: geometry, x_coord: float, y_coord: float, radius: float) → bool

Returns the true if the geometry is a point and is inside the circle. Returns false otherwise.

+		Immutable
st_pointn(geometry: geometry, n: int) → geometry

Returns the n-th Point of a LineString (1-indexed). Returns NULL if out of bounds or not a LineString.

+		Immutable
st_pointonsurface(geometry: geometry) → geometry

Returns a point that intersects with the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_points(geometry: geometry) → geometry

Returns all coordinates in the given Geometry as a MultiPoint, including duplicates.

+		Immutable
st_polyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygon(geometry: geometry, srid: int) → geometry

Returns a new Polygon from the given LineString and sets its SRID. It is equivalent to ST_MakePolygon with a single argument followed by ST_SetSRID.

+		Immutable
st_polygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_project(geography: geography, distance: float, azimuth: float) → geography

Returns a point projected from a start point along a geodesic using a given distance and azimuth (bearing). +This is known as the direct geodesic problem.

+

The distance is given in meters. Negative values are supported.

+

The azimuth (also known as heading or bearing) is given in radians. It is measured clockwise from true north (azimuth zero). +East is azimuth π/2 (90 degrees); south is azimuth π (180 degrees); west is azimuth 3π/2 (270 degrees). +Negative azimuth values and values greater than 2π (360 degrees) are supported.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, bnr: int) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b using the given boundary node rule (1:OGC/MOD2, 2:Endpoint, 3:MultivalentEndpoint, 4:MonovalentEndpoint).

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, pattern: string) → bool

Returns whether the DE-9IM spatial relation between geometry_a and geometry_b matches the DE-9IM pattern.

+

This function utilizes the GEOS module.

+		Immutable
st_relatematch(intersection_matrix: string, pattern: string) → bool

Returns whether the given DE-9IM intersection matrix satisfies the given pattern.

+		Immutable
st_removepoint(line_string: geometry, index: int) → geometry

Removes the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_removerepeatedpoints(geometry: geometry) → geometry

Returns a geometry with repeated points removed.

+		Immutable
st_removerepeatedpoints(geometry: geometry, tolerance: float) → geometry

Returns a geometry with repeated points removed, within the given distance tolerance.

+		Immutable
st_reverse(geometry: geometry) → geometry

Returns a modified geometry by reversing the order of its vertices.

+		Immutable
st_rotate(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_point: geometry) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_x: float, origin_y: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotatex(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the x axis by a rotation angle.

+		Immutable
st_rotatey(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the y axis by a rotation angle.

+		Immutable
st_rotatez(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the z axis by a rotation angle.

+		Immutable
st_s2covering(geography: geography) → geography

Returns a geography which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geography: geography, settings: string) → geography

Returns a geography which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geography, 's2_max_level=15,s2_level_mod=3').

+		Immutable
st_s2covering(geometry: geometry) → geometry

Returns a geometry which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geometry: geometry, settings: string) → geometry

Returns a geometry which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geometry, 's2_max_level=15,s2_level_mod=3')

+		Immutable
st_scale(g: geometry, factor: geometry) → geometry

Returns a modified Geometry scaled by taking in a Geometry as the factor.

+		Immutable
st_scale(g: geometry, factor: geometry, origin: geometry) → geometry

Returns a modified Geometry scaled by the Geometry factor relative to a false origin.

+		Immutable
st_scale(geometry: geometry, x_factor: float, y_factor: float) → geometry

Returns a modified Geometry scaled by the given factors.

+		Immutable
st_segmentize(geography: geography, max_segment_length_meters: float) → geography

Returns a modified Geography having no segment longer than the given max_segment_length meters.

+

The calculations are done on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_segmentize(geometry: geometry, max_segment_length: float) → geometry

Returns a modified Geometry having no segment longer than the given max_segment_length. Length units are in units of spatial reference.

+		Immutable
st_setpoint(line_string: geometry, index: int, point: geometry) → geometry

Sets the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_setsrid(geography: geography, srid: int) → geography

Sets a Geography to a new SRID without transforming the coordinates.

+		Immutable
st_setsrid(geometry: geometry, srid: int) → geometry

Sets a Geometry to a new SRID without transforming the coordinates.

+		Immutable
st_sharedpaths(geometry_a: geometry, geometry_b: geometry) → geometry

Returns a collection containing paths shared by the two input geometries.

+

Those going in the same direction are in the first element of the collection, +those going in the opposite direction are in the second element. +The paths themselves are given in the direction of the first geometry.

+		Immutable
st_shiftlongitude(geometry: geometry) → geometry

Returns a modified version of a geometry in which the longitude (X coordinate) of each point is incremented by 360 if it is <0 and decremented by 360 if it is >180. The result is only meaningful if the coordinates are in longitude/latitude.

+		Immutable
st_shortestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the minimum distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the minimum distance between the geometry’s vertexes. The function will return the shortest line that was discovered first when comparing minimum distances if more than one is found.

+		Immutable
st_simplify(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm.

+

This function utilizes the GEOS module.

+		Immutable
st_simplify(geometry: geometry, tolerance: float, preserve_collapsed: bool) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, retaining objects that would be too small given the tolerance if preserve_collapsed is set to true.

+		Immutable
st_simplifypreservetopology(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, avoiding the creation of invalid geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_snap(input: geometry, target: geometry, tolerance: float) → geometry

Snaps the vertices and segments of input geometry the target geometry’s vertices. +Tolerance is used to control where snapping is performed. The result geometry is the input geometry with the vertices snapped. +If no snapping occurs then the input geometry is returned unchanged.

+		Immutable
st_snaptogrid(geometry: geometry, origin: geometry, size_x: float, size_y: float, size_z: float, size_m: float) → geometry

Snap a geometry to a grid defined by the given origin and X, Y, Z, and M cell sizes. Any dimension with a 0 cell size will not be snapped.

+		Immutable
st_snaptogrid(geometry: geometry, origin_x: float, origin_y: float, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y based on an origin of (origin_x, origin_y).

+		Immutable
st_snaptogrid(geometry: geometry, size: float) → geometry

Snap a geometry to a grid of the given size. The specified size is only used to snap X and Y coordinates.

+		Immutable
st_snaptogrid(geometry: geometry, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y.

+		Immutable
st_srid(geography: geography) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geography as defined in spatial_ref_sys table.

+		Immutable
st_srid(geometry: geometry) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geometry as defined in spatial_ref_sys table.

+		Immutable
st_startpoint(geometry: geometry) → geometry

Returns the first point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_subdivide(geometry: geometry) → geometry

Returns a geometry divided into parts, where each part contains no more than 256 vertices.

+		Immutable
st_subdivide(geometry: geometry, max_vertices: int4) → geometry

Returns a geometry divided into parts, where each part contains no more than the number of vertices provided.

+		Immutable
st_summary(geography: geography) → string

Returns a text summary of the contents of the geography.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_summary(geometry: geometry) → string

Returns a text summary of the contents of the geometry.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_swapordinates(geometry: geometry, swap_ordinate_string: string) → geometry

Returns a version of the given geometry with given ordinates swapped. +The swap_ordinate_string parameter is a 2-character string naming the ordinates to swap. Valid names are: x, y, z and m.

+		Immutable
st_symdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_symmetricdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4, bounds: geometry) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4, bounds: geometry, margin: float) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, srid: int) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates. The supplied SRID is set on the new geometry.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, srid: int) → geometry

Transforms a geometry into the given SRID coordinate reference system by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system referenced by the projection text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float, delta_z: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_transscale(geometry: geometry, delta_x: float, delta_y: float, x_factor: float, y_factor: float) → geometry

Translates the geometry using the deltaX and deltaY args, then scales it using the XFactor, YFactor args, working in 2D only.

+		Immutable
st_unaryunion(geometry: geometry) → geometry

Returns a union of the components for any geometry or geometry collection provided. Dissolves boundaries of a multipolygon.

+		Immutable
st_voronoilines(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoipolygons(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_wkbtosql(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_wkttosql(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_x(geometry: geometry) → float

Returns the X coordinate of a geometry if it is a Point.

+		Immutable
st_xmax(box2d: box2d) → float

Returns the maximum X ordinate of a box2d.

+		Immutable
st_xmax(geometry: geometry) → float

Returns the maximum X ordinate of a geometry.

+		Immutable
st_xmin(box2d: box2d) → float

Returns the minimum X ordinate of a box2d.

+		Immutable
st_xmin(geometry: geometry) → float

Returns the minimum X ordinate of a geometry.

+		Immutable
st_y(geometry: geometry) → float

Returns the Y coordinate of a geometry if it is a Point.

+		Immutable
st_ymax(box2d: box2d) → float

Returns the maximum Y ordinate of a box2d.

+		Immutable
st_ymax(geometry: geometry) → float

Returns the maximum Y ordinate of a geometry.

+		Immutable
st_ymin(box2d: box2d) → float

Returns the minimum Y ordinate of a box2d.

+		Immutable
st_ymin(geometry: geometry) → float

Returns the minimum Y ordinate of a geometry.

+		Immutable
st_z(geometry: geometry) → float

Returns the Z coordinate of a geometry if it is a Point.

+		Immutable
st_zmflag(geometry: geometry) → int2

Returns a code based on the ZM coordinate dimension of a geometry (XY = 0, XYM = 1, XYZ = 2, XYZM = 3).

+		Immutable
+ +### String and byte functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ascii(val: string) → int

Returns the character code of the first character in val. Despite the name, the function supports Unicode too.

+		Immutable
bit_count(val: bytes) → int

Calculates the number of bits set used to represent val.

+		Immutable
bit_count(val: varbit) → int

Calculates the number of bits set used to represent val.

+		Immutable
bit_length(val: bytes) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: string) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
bitmask_and(a: string, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: string, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
btrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning or end of input (applies recursively).

+

For example, btrim('doggie', 'eod') returns ggi.

+		Immutable
btrim(val: string) → string

Removes all spaces from the beginning and end of val.

+		Immutable
char_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
char_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
character_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
character_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
chr(val: int) → string

Returns the character with the code given in val. Inverse function of ascii().

+		Immutable
compress(data: bytes, codec: string) → bytes

Compress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
concat(anyelement...) → string

Concatenates a comma-separated list of strings.

+		Immutable
concat_ws(string...) → string

Uses the first argument as a separator between the concatenation of the subsequent arguments.

+

For example concat_ws('!','wow','great') returns wow!great.

+		Immutable
convert_from(str: bytes, enc: string) → string

Decode the bytes in str into a string using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
convert_to(str: string, enc: string) → bytes

Encode the string str as a byte array using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
decode(text: string, format: string) → bytes

Decodes data using format (hex / escape / base64).

+		Immutable
decompress(data: bytes, codec: string) → bytes

Decompress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
difference(source: string, target: string) → int

Convert two strings to their Soundex codes and report the number of matching code positions.

+		Immutable
encode(data: bytes, format: string) → string

Encodes data using format (hex / escape / base64).

+		Immutable
format(string, anyelement...) → string

Interprets the first argument as a format string similar to C sprintf and interpolates the remaining arguments.

+		Stable
from_ip(val: bytes) → string

Converts the byte string representation of an IP to its character string representation.

+		Immutable
from_uuid(val: bytes) → string

Converts the byte string representation of a UUID to its character string representation.

+		Immutable
get_bit(bit_string: varbit, index: int) → int

Extracts a bit at given index in the bit array.

+		Immutable
get_bit(byte_string: bytes, index: int) → int

Extracts a bit at the given index in the byte array.

+		Immutable
get_byte(byte_string: bytes, index: int) → int

Extracts a byte at the given index in the byte array.

+		Immutable
initcap(val: string) → string

Capitalizes the first letter of val.

+		Immutable
left(input: bytes, return_set: int) → bytes

Returns the first return_set bytes from input.

+		Immutable
left(input: string, return_set: int) → string

Returns the first return_set characters from input.

+		Immutable
length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
length(val: string) → int

Calculates the number of characters in val.

+		Immutable
length(val: varbit) → int

Calculates the number of bits in val.

+		Immutable
lower(val: string) → string

Converts all characters in val to their lower-case equivalents.

+		Immutable
lpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the left of string.If string is longer than length it is truncated.

+		Immutable
lpad(string: string, length: int, fill: string) → string

Pads string by adding fill to the left of string to make it length. If string is longer than length it is truncated.

+		Immutable
ltrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning (left-hand side) of input (applies recursively).

+

For example, ltrim('doggie', 'od') returns ggie.

+		Immutable
ltrim(val: string) → string

Removes all spaces from the beginning (left-hand side) of val.

+		Immutable
md5(bytes...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
md5(string...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
octet_length(val: bytes) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: string) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int) → string

Replaces characters in input with overlay_val starting at start_pos (begins at 1).

+

For example, overlay('doggie', 'CAT', 2) returns dCATie.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int, end_pos: int) → string

Deletes the characters in input between start_pos and end_pos (count starts at 1), and then insert overlay_val at start_pos.

+		Immutable
parse_date(string: string, datestyle: string) → date

Parses a date assuming it is in format specified by DateStyle.

+		Immutable
parse_date(val: string) → date

Parses a date assuming it is in MDY format.

+		Immutable
parse_ident(qualified_identifier: string) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. Extra characters after the last identifier are considered an error

+		Immutable
parse_ident(qualified_identifier: string, strict: bool) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. If strict is false, then extra characters after the last identifier are ignored.

+		Immutable
parse_interval(string: string, style: string) → interval

Convert a string to an interval using the given IntervalStyle.

+		Immutable
parse_interval(val: string) → interval

Convert a string to an interval assuming the Postgres IntervalStyle.

+		Immutable
parse_time(string: string, timestyle: string) → time

Parses a time assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_time(val: string) → time

Parses a time assuming the date (if any) is in MDY format.

+		Immutable
parse_timestamp(string: string, datestyle: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates formatted using the given DateStyle.

+		Immutable
parse_timestamp(val: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates are in MDY format.

+		Immutable
parse_timetz(string: string, timestyle: string) → timetz

Parses a timetz assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_timetz(val: string) → timetz

Parses a timetz assuming the date (if any) is in MDY format.

+		Immutable
prettify_statement(statement: string, line_width: int, align_mode: int, case_mode: int) → string

Prettifies a statement using a user-configured pretty-printing config. +Align mode values range from 0 - 3, representing no, partial, full, and extra alignment respectively. +Case mode values range between 0 - 1, representing lower casing and upper casing respectively.

+		Immutable
prettify_statement(val: string) → string

Prettifies a statement using a the default pretty-printing config.

+		Immutable
quote_ident(val: string) → string

Return val suitably quoted to serve as identifier in a SQL statement.

+		Immutable
quote_literal(val: string) → string

Return val suitably quoted to serve as string literal in a SQL statement.

+		Immutable
quote_literal(val: anyelement) → string

Coerce val to a string and then quote it as a literal.

+		Stable
quote_nullable(val: string) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Immutable
quote_nullable(val: anyelement) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Stable
regexp_extract(input: string, regex: string) → string

Returns the first match for the Regular Expression regex in input.

+		Immutable
regexp_replace(input: string, regex: string, replace: string) → string

Replaces matches for the Regular Expression regex in input with the Regular Expression replace.

+		Immutable
regexp_replace(input: string, regex: string, replace: string, flags: string) → string

Replaces matches for the regular expression regex in input with the regular expression replace using flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
repeat(input: string, repeat_counter: int) → string

Concatenates input repeat_counter number of times.

+

For example, repeat('dog', 2) returns dogdog.

+		Immutable
replace(input: string, find: string, replace: string) → string

Replaces all occurrences of find with replace in input

+		Immutable
reverse(val: string) → string

Reverses the order of the string’s characters.

+		Immutable
right(input: bytes, return_set: int) → bytes

Returns the last return_set bytes from input.

+		Immutable
right(input: string, return_set: int) → string

Returns the last return_set characters from input.

+		Immutable
rpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the right of string. If string is longer than length it is truncated.

+		Immutable
rpad(string: string, length: int, fill: string) → string

Pads string to length by adding fill to the right of string. If string is longer than length it is truncated.

+		Immutable
rtrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the end (right-hand side) of input (applies recursively).

+

For example, rtrim('doggie', 'ei') returns dogg.

+		Immutable
rtrim(val: string) → string

Removes all spaces from the end (right-hand side) of val.

+		Immutable
set_bit(bit_string: varbit, index: int, to_set: int) → varbit

Updates a bit at given index in the bit array.

+		Immutable
set_bit(byte_string: bytes, index: int, to_set: int) → bytes

Updates a bit at the given index in the byte array.

+		Immutable
set_byte(byte_string: bytes, index: int, to_set: int) → bytes

Updates a byte at the given index in the byte array.

+		Immutable
sha1(bytes...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha1(string...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha224(bytes...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha224(string...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha256(bytes...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha256(string...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha384(bytes...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha384(string...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha512(bytes...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
sha512(string...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
similar_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_to_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
split_part(input: string, delimiter: string, return_index_pos: int) → string

Splits input on delimiter and return the value in the return_index_pos position (starting at 1).

+

For example, split_part('123.456.789.0','.',3)returns 789.

+		Immutable
strpos(input: bytes, find: bytes) → int

Calculates the position where the byte subarray find begins in input.

+		Immutable
strpos(input: string, find: string) → int

Calculates the position where the string find begins in input.

+

For example, strpos('doggie', 'gie') returns 4.

+		Immutable
strpos(input: varbit, find: varbit) → int

Calculates the position where the bit subarray find begins in input.

+		Immutable
substr(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substr(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substr(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substring(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substring(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
to_char_with_style(date: date, datestyle: string) → string

Convert an date to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_char_with_style(interval: interval, style: string) → string

Convert an interval to a string using the given IntervalStyle.

+		Immutable
to_char_with_style(timestamp: timestamp, datestyle: string) → string

Convert an timestamp to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_english(val: int) → string

This function enunciates the value of its argument using English cardinals.

+		Immutable
to_hex(val: bytes) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: int) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: string) → string

Converts val to its hexadecimal representation.

+		Immutable
to_ip(val: string) → bytes

Converts the character string representation of an IP to its byte string representation.

+		Immutable
to_uuid(val: string) → bytes

Converts the character string representation of a UUID to its byte string representation.

+		Immutable
translate(input: string, find: string, replace: string) → string

In input, replaces the first character from find with the first character in replace; repeat for each character in find.

+

For example, translate('doggie', 'dog', '123'); returns 1233ie.

+		Immutable
ulid_to_uuid(val: string) → uuid

Converts a ULID string to its UUID-encoded representation.

+		Immutable
unaccent(val: string) → string

Removes accents (diacritic signs) from the text provided in val.

+		Immutable
upper(val: string) → string

Converts all characters in val to their to their upper-case equivalents.

+		Immutable
+ +### System info functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cluster_logical_timestamp() → decimal

Returns the logical time of the current transaction as +a CockroachDB HLC in decimal form.

+

Note that uses of this function disable server-side optimizations and +may increase either contention or retry errors, or both.

+

Returns an error if run in a transaction with an isolation level weaker than SERIALIZABLE.

+		Volatile
current_database() → string

Returns the current database.

+		Stable
current_schema() → string

Returns the current schema.

+		Stable
current_schemas(include_pg_catalog: bool) → string[]

Returns the valid schemas in the search path.

+		Stable
current_user() → string

Returns the current user. This function is provided for compatibility with PostgreSQL.

+		Stable
session_user() → string

Returns the session user. This function is provided for compatibility with PostgreSQL.

+		Stable
to_regclass(text: string) → regtype

Translates a textual relation name to its OID

+		Stable
to_regnamespace(text: string) → regtype

Translates a textual schema name to its OID

+		Stable
to_regproc(text: string) → regtype

Translates a textual function or procedure name to its OID

+		Stable
to_regprocedure(text: string) → regtype

Translates a textual function or procedure name(with argument types) to its OID

+		Stable
to_regrole(text: string) → regtype

Translates a textual role name to its OID

+		Stable
to_regtype(text: string) → regtype

Translates a textual type name to its OID

+		Stable
version() → string

Returns the node’s version of CockroachDB.

+		Volatile
+ +### TIMETZ functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
current_time() → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time() → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_time(precision: int) → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time(precision: int) → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → timetz

Returns the current transaction’s time with time zone.

+		Stable
localtime(precision: int) → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime(precision: int) → timetz

Returns the current transaction’s time with time zone.

+		Stable
+ +### Trigrams functions + + + + + + +
Function → ReturnsDescriptionVolatility
show_trgm(input: string) → string[]

Returns an array of all the trigrams in the given string.

+		Immutable
similarity(left: string, right: string) → float

Returns a number that indicates how similar the two arguments are. The range of the result is zero (indicating that the two strings are completely dissimilar) to one (indicating that the two strings are identical).

+		Immutable
+ +### UUID functions + + + + + +
Function → ReturnsDescriptionVolatility
uuid_to_ulid(val: uuid) → string

Converts a UUID-encoded ULID to its string representation.

+		Immutable
+ +### Compatibility functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
col_description(table_oid: oid, column_number: int) → string

Returns the comment for a table column, which is specified by the OID of its table and its column number. (obj_description cannot be used for table columns, since columns do not have OIDs of their own.)

+		Stable
current_setting(setting_name: string) → string

System info

+		Stable
current_setting(setting_name: string, missing_ok: bool) → string

System info

+		Stable
format_type(type_oid: oid, typemod: int) → string

Returns the SQL name of a data type that is identified by its type OID and possibly a type modifier. Currently, the type modifier is ignored.

+		Stable
getdatabaseencoding() → string

Returns the current encoding name used by the database.

+		Stable
has_any_column_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_column_privilege(table: string, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: string, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_database_privilege(database: string, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(database: oid, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(user: string, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: string, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_foreign_data_wrapper_privilege(fdw: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(fdw: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_function_privilege(function: string, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(function: oid, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(user: string, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: string, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_language_privilege(language: string, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(language: oid, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(user: string, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: string, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_schema_privilege(schema: string, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(schema: oid, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_sequence_privilege(sequence: string, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(sequence: oid, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_server_privilege(server: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(server: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_table_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_tablespace_privilege(tablespace: string, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(tablespace: oid, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_type_privilege(type: string, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(type: oid, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(user: string, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: string, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
information_schema._pg_numeric_precision(typid: oid, typmod: int4) → int

Returns the precision of the given type with type modifier

+		Immutable
information_schema._pg_numeric_precision_radix(typid: oid, typmod: int4) → int

Returns the radix of the given type with type modifier

+		Immutable
information_schema._pg_numeric_scale(typid: oid, typmod: int4) → int

Returns the scale of the given type with type modifier

+		Immutable
nameconcatoid(name: string, oid: oid) → name

Used in the information_schema to produce specific_name columns, which are supposed to be unique per schema. The result is the same as ($1::text || ‘_’ || $2::text)::name except that, if it would not fit in 63 characters, we make it do so by truncating the name input (not the oid).

+		Immutable
obj_description(object_oid: oid) → string

Returns the comment for a database object specified by its OID alone. This is deprecated since there is no guarantee that OIDs are unique across different system catalogs; therefore, the wrong comment might be returned.

+		Stable
obj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a database object specified by its OID and the name of the containing system catalog. For example, obj_description(123456, ‘pg_class’) would retrieve the comment for the table with OID 123456.

+		Stable
oidvectortypes(vector: oidvector) → string

Generates a comma seperated string of type names from an oidvector.

+		Stable
pg_backend_pid() → int

Returns a numerical ID attached to this session. This ID is part of the query cancellation key used by the wire protocol. This function was only added for compatibility, and unlike in Postgres, the returned value does not correspond to a real process ID.

+		Stable
pg_collation_for(str: anyelement) → string

Returns the collation of the argument

+		Stable
pg_column_is_updatable(reloid: oid, attnum: int2, include_triggers: bool) → bool

Returns whether the given column can be updated.

+		Stable
pg_column_size(anyelement...) → int

Return size in bytes of the column provided as an argument

+		Immutable
pg_function_is_visible(oid: oid) → bool

Returns whether the function with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_get_function_arg_default(func_oid: oid, arg_num: int4) → string

Get textual representation of a function argument’s default value. The second argument of this function is the argument number among all arguments (i.e. proallargtypes, not proargtypes), starting with 1, because that’s how information_schema.sql uses it. Currently, this always returns NULL, since CockroachDB does not support default values.

+		Stable
pg_get_function_arguments(func_oid: oid) → string

Returns the argument list (with defaults) necessary to identify a function, in the form it would need to appear in within CREATE FUNCTION.

+		Stable
pg_get_function_identity_arguments(func_oid: oid) → string

Returns the argument list (without defaults) necessary to identify a function, in the form it would need to appear in within ALTER FUNCTION, for instance.

+		Stable
pg_get_function_result(func_oid: oid) → string

Returns the types of the result of the specified function.

+		Stable
pg_get_functiondef(func_oid: oid) → string

For user-defined functions, returns the definition of the specified function. For builtin functions, returns the name of the function.

+		Stable
pg_get_indexdef(index_oid: oid) → string

Gets the CREATE INDEX command for index

+		Stable
pg_get_indexdef(index_oid: oid, column_no: int, pretty_bool: bool) → string

Gets the CREATE INDEX command for index, or definition of just one index column when given a non-zero column number

+		Stable
pg_get_serial_sequence(table_name: string, column_name: string) → string

Returns the name of the sequence used by the given column_name in the table table_name.

+		Stable
pg_get_viewdef(view_oid: oid) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_get_viewdef(view_oid: oid, pretty_bool: bool) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_has_role(role: string, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(role: oid, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(user: string, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: string, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_is_other_temp_schema(oid: oid) → bool

Returns true if the given OID is the OID of another session’s temporary schema. (This can be useful, for example, to exclude other sessions’ temporary tables from a catalog display.)

+		Stable
pg_my_temp_schema() → oid

Returns the OID of the current session’s temporary schema, or zero if it has none (because it has not created any temporary tables).

+		Stable
pg_relation_is_updatable(reloid: oid, include_triggers: bool) → int4

Returns the update events the relation supports.

+		Stable
pg_sequence_last_value(sequence_oid: oid) → int

Returns the last value generated by a sequence, or NULL if the sequence has not been used yet.

+		Volatile
pg_sleep(seconds: float) → bool

pg_sleep makes the current session’s process sleep until seconds seconds have elapsed. seconds is a value of type double precision, so fractional-second delays can be specified.

+		Volatile
pg_table_is_visible(oid: oid) → bool

Returns whether the table with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_type_is_visible(oid: oid) → bool

Returns whether the type with the given OID belongs to one of the schemas on the search path.

+		Stable
set_config(setting_name: string, new_value: string, is_local: bool) → string

System info

+		Volatile
shobj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a shared database object specified by its OID and the name of the containing system catalog. This is just like obj_description except that it is used for retrieving comments on shared objects (e.g. databases).

+		Stable
+ diff --git a/src/current/_includes/cockroach-generated/release-24.3/sql/operators.md b/src/current/_includes/cockroach-generated/release-24.3/sql/operators.md new file mode 100644 index 00000000000..47027b064fe --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.3/sql/operators.md @@ -0,0 +1,658 @@ + + + + + +
#Return
int # intint
varbit # varbitvarbit
+ + + + +
#>Return
jsonb #> string[]jsonb
+ + + + +
#>>Return
jsonb #>> string[]string
+ + + + + + + + + +
%Return
decimal % decimaldecimal
decimal % intdecimal
float % floatfloat
int % decimaldecimal
int % intint
string % stringbool
+ + + + + + +
&Return
inet & inetinet
int & intint
varbit & varbitvarbit
+ + + + + + + + + +
&&Return
anyelement && anyelementbool
box2d && box2dbool
box2d && geometrybool
geometry && box2dbool
geometry && geometrybool
inet && inetbool
+ + + + + + + + + + + + + + + +
*Return
decimal * decimaldecimal
decimal * intdecimal
decimal * intervalinterval
float * floatfloat
float * intervalinterval
int * decimaldecimal
int * intint
int * intervalinterval
interval * decimalinterval
interval * floatinterval
interval * intinterval
vector * vectorvector
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Return
+decimaldecimal
+floatfloat
+intint
+intervalinterval
date + intdate
date + intervaltimestamp
date + timetimestamp
date + timetztimestamptz
decimal + decimaldecimal
decimal + intdecimal
decimal + pg_lsnpg_lsn
float + floatfloat
inet + intinet
int + datedate
int + decimaldecimal
int + inetinet
int + intint
interval + datetimestamp
interval + intervalinterval
interval + timetime
interval + timestamptimestamp
interval + timestamptztimestamptz
interval + timetztimetz
pg_lsn + decimalpg_lsn
time + datetimestamp
time + intervaltime
timestamp + intervaltimestamp
timestamptz + intervaltimestamptz
timetz + datetimestamptz
timetz + intervaltimetz
vector + vectorvector
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
-Return
-decimaldecimal
-floatfloat
-intint
-intervalinterval
date - dateint
date - intdate
date - intervaltimestamp
date - timetimestamp
decimal - decimaldecimal
decimal - intdecimal
float - floatfloat
inet - inetint
inet - intinet
int - decimaldecimal
int - intint
interval - intervalinterval
jsonb - intjsonb
jsonb - stringjsonb
jsonb - string[]jsonb
pg_lsn - decimalpg_lsn
pg_lsn - pg_lsndecimal
time - intervaltime
time - timeinterval
timestamp - intervaltimestamp
timestamp - timestampinterval
timestamp - timestamptzinterval
timestamptz - intervaltimestamptz
timestamptz - timestampinterval
timestamptz - timestamptzinterval
timetz - intervaltimetz
vector - vectorvector
+ + + + + +
->Return
jsonb -> intjsonb
jsonb -> stringjsonb
+ + + + + +
->>Return
jsonb ->> intstring
jsonb ->> stringstring
+ + + + + + + + + + +
/Return
decimal / decimaldecimal
decimal / intdecimal
float / floatfloat
int / decimaldecimal
int / intdecimal
interval / floatinterval
interval / intinterval
+ + + + + + + + +
//Return
decimal // decimaldecimal
decimal // intdecimal
float // floatfloat
int // decimaldecimal
int // intint
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<Return
anyenum < anyenumbool
bool < boolbool
bool[] < bool[]bool
box2d < box2dbool
bpchar < bpcharbool
bytes < bytesbool
bytes[] < bytes[]bool
collatedstring < collatedstringbool
date < datebool
date < timestampbool
date < timestamptzbool
date[] < date[]bool
decimal < decimalbool
decimal < floatbool
decimal < intbool
decimal[] < decimal[]bool
float < decimalbool
float < floatbool
float < intbool
float[] < float[]bool
geography < geographybool
geometry < geometrybool
inet < inetbool
inet[] < inet[]bool
int < decimalbool
int < floatbool
int < intbool
int < oidbool
int[] < int[]bool
interval < intervalbool
interval[] < interval[]bool
jsonb < jsonbbool
oid < intbool
oid < oidbool
pg_lsn < pg_lsnbool
refcursor < refcursorbool
string < stringbool
string[] < string[]bool
time < timebool
time < timetzbool
time[] < time[]bool
timestamp < datebool
timestamp < timestampbool
timestamp < timestamptzbool
timestamp[] < timestamp[]bool
timestamptz < datebool
timestamptz < timestampbool
timestamptz < timestamptzbool
timestamptz < timestamptzbool
timetz < timebool
timetz < timetzbool
tuple < tuplebool
uuid < uuidbool
uuid[] < uuid[]bool
varbit < varbitbool
vector < vectorbool
+ + + + +
<#>Return
vector <#> vectorfloat
+ + + + +
<->Return
vector <-> vectorfloat
+ + + + + + +
<<Return
inet << inetbool
int << intint
varbit << intvarbit
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<=Return
anyenum <= anyenumbool
bool <= boolbool
bool[] <= bool[]bool
box2d <= box2dbool
bpchar <= bpcharbool
bytes <= bytesbool
bytes[] <= bytes[]bool
collatedstring <= collatedstringbool
date <= datebool
date <= timestampbool
date <= timestamptzbool
date[] <= date[]bool
decimal <= decimalbool
decimal <= floatbool
decimal <= intbool
decimal[] <= decimal[]bool
float <= decimalbool
float <= floatbool
float <= intbool
float[] <= float[]bool
geography <= geographybool
geometry <= geometrybool
inet <= inetbool
inet[] <= inet[]bool
int <= decimalbool
int <= floatbool
int <= intbool
int <= oidbool
int[] <= int[]bool
interval <= intervalbool
interval[] <= interval[]bool
jsonb <= jsonbbool
oid <= intbool
oid <= oidbool
pg_lsn <= pg_lsnbool
refcursor <= refcursorbool
string <= stringbool
string[] <= string[]bool
time <= timebool
time <= timetzbool
time[] <= time[]bool
timestamp <= datebool
timestamp <= timestampbool
timestamp <= timestamptzbool
timestamp[] <= timestamp[]bool
timestamptz <= datebool
timestamptz <= timestampbool
timestamptz <= timestamptzbool
timestamptz <= timestamptzbool
timetz <= timebool
timetz <= timetzbool
tuple <= tuplebool
uuid <= uuidbool
uuid[] <= uuid[]bool
varbit <= varbitbool
vector <= vectorbool
+ + + + +
<=>Return
vector <=> vectorfloat
+ + + + + +
<@Return
anyelement <@ anyelementbool
jsonb <@ jsonbbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
=Return
anyenum = anyenumbool
bool = boolbool
bool[] = bool[]bool
box2d = box2dbool
bpchar = bpcharbool
bytes = bytesbool
bytes[] = bytes[]bool
collatedstring = collatedstringbool
date = datebool
date = timestampbool
date = timestamptzbool
date[] = date[]bool
decimal = decimalbool
decimal = floatbool
decimal = intbool
decimal[] = decimal[]bool
float = decimalbool
float = floatbool
float = intbool
float[] = float[]bool
geography = geographybool
geometry = geometrybool
inet = inetbool
inet[] = inet[]bool
int = decimalbool
int = floatbool
int = intbool
int = oidbool
int[] = int[]bool
interval = intervalbool
interval[] = interval[]bool
jsonb = jsonbbool
oid = intbool
oid = oidbool
pg_lsn = pg_lsnbool
refcursor = refcursorbool
string = stringbool
string[] = string[]bool
time = timebool
time = timetzbool
time[] = time[]bool
timestamp = datebool
timestamp = timestampbool
timestamp = timestamptzbool
timestamp[] = timestamp[]bool
timestamptz = datebool
timestamptz = timestampbool
timestamptz = timestamptzbool
timestamptz = timestamptzbool
timetz = timebool
timetz = timetzbool
tsquery = tsquerybool
tsvector = tsvectorbool
tuple = tuplebool
uuid = uuidbool
uuid[] = uuid[]bool
varbit = varbitbool
vector = vectorbool
+ + + + + + +
>>Return
inet >> inetbool
int >> intint
varbit >> intvarbit
+ + + + +
?Return
jsonb ? stringbool
+ + + + +
?&Return
jsonb ?& string[]bool
+ + + + +
?|Return
jsonb ?| string[]bool
+ + + + + +
@>Return
anyelement @> anyelementbool
jsonb @> jsonbbool
+ + + + + +
@@Return
tsquery @@ tsvectorbool
tsvector @@ tsquerybool
+ + + + +
ILIKEReturn
string ILIKE stringbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
INReturn
anyenum IN tuplebool
bool IN tuplebool
box2d IN tuplebool
bpchar IN tuplebool
bytes IN tuplebool
collatedstring IN tuplebool
date IN tuplebool
decimal IN tuplebool
float IN tuplebool
geography IN tuplebool
geometry IN tuplebool
inet IN tuplebool
int IN tuplebool
interval IN tuplebool
jsonb IN tuplebool
oid IN tuplebool
pg_lsn IN tuplebool
refcursor IN tuplebool
string IN tuplebool
time IN tuplebool
timestamp IN tuplebool
timestamptz IN tuplebool
timetz IN tuplebool
tuple IN tuplebool
uuid IN tuplebool
varbit IN tuplebool
vector IN tuplebool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IS NOT DISTINCT FROMReturn
anyelement IS NOT DISTINCT FROM unknownbool
anyenum IS NOT DISTINCT FROM anyenumbool
bool IS NOT DISTINCT FROM boolbool
bool[] IS NOT DISTINCT FROM bool[]bool
box2d IS NOT DISTINCT FROM box2dbool
bpchar IS NOT DISTINCT FROM bpcharbool
bytes IS NOT DISTINCT FROM bytesbool
bytes[] IS NOT DISTINCT FROM bytes[]bool
collatedstring IS NOT DISTINCT FROM collatedstringbool
date IS NOT DISTINCT FROM datebool
date IS NOT DISTINCT FROM timestampbool
date IS NOT DISTINCT FROM timestamptzbool
date[] IS NOT DISTINCT FROM date[]bool
decimal IS NOT DISTINCT FROM decimalbool
decimal IS NOT DISTINCT FROM floatbool
decimal IS NOT DISTINCT FROM intbool
decimal[] IS NOT DISTINCT FROM decimal[]bool
float IS NOT DISTINCT FROM decimalbool
float IS NOT DISTINCT FROM floatbool
float IS NOT DISTINCT FROM intbool
float[] IS NOT DISTINCT FROM float[]bool
geography IS NOT DISTINCT FROM geographybool
geometry IS NOT DISTINCT FROM geometrybool
inet IS NOT DISTINCT FROM inetbool
inet[] IS NOT DISTINCT FROM inet[]bool
int IS NOT DISTINCT FROM decimalbool
int IS NOT DISTINCT FROM floatbool
int IS NOT DISTINCT FROM intbool
int IS NOT DISTINCT FROM oidbool
int[] IS NOT DISTINCT FROM int[]bool
interval IS NOT DISTINCT FROM intervalbool
interval[] IS NOT DISTINCT FROM interval[]bool
jsonb IS NOT DISTINCT FROM jsonbbool
oid IS NOT DISTINCT FROM intbool
oid IS NOT DISTINCT FROM oidbool
pg_lsn IS NOT DISTINCT FROM pg_lsnbool
refcursor IS NOT DISTINCT FROM refcursorbool
string IS NOT DISTINCT FROM stringbool
string[] IS NOT DISTINCT FROM string[]bool
time IS NOT DISTINCT FROM timebool
time IS NOT DISTINCT FROM timetzbool
time[] IS NOT DISTINCT FROM time[]bool
timestamp IS NOT DISTINCT FROM datebool
timestamp IS NOT DISTINCT FROM timestampbool
timestamp IS NOT DISTINCT FROM timestamptzbool
timestamp[] IS NOT DISTINCT FROM timestamp[]bool
timestamptz IS NOT DISTINCT FROM datebool
timestamptz IS NOT DISTINCT FROM timestampbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timetz IS NOT DISTINCT FROM timebool
timetz IS NOT DISTINCT FROM timetzbool
tsquery IS NOT DISTINCT FROM tsquerybool
tsvector IS NOT DISTINCT FROM tsvectorbool
tuple IS NOT DISTINCT FROM tuplebool
unknown IS NOT DISTINCT FROM unknownbool
unknown IS NOT DISTINCT FROM voidbool
uuid IS NOT DISTINCT FROM uuidbool
uuid[] IS NOT DISTINCT FROM uuid[]bool
varbit IS NOT DISTINCT FROM varbitbool
vector IS NOT DISTINCT FROM vectorbool
void IS NOT DISTINCT FROM unknownbool
+ + + + +
LIKEReturn
string LIKE stringbool
+ + + + +
SIMILAR TOReturn
string SIMILAR TO stringbool
+ + + + + + + + +
^Return
decimal ^ decimaldecimal
decimal ^ intdecimal
float ^ floatfloat
int ^ decimaldecimal
int ^ intint
+ + + + + + +
|Return
inet | inetinet
int | intint
varbit | varbitvarbit
+ + + + + +
|/Return
|/decimaldecimal
|/floatfloat
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
||Return
bool || bool[]bool[]
bool || stringstring
bool[] || boolbool[]
bool[] || bool[]bool[]
box2d || box2dbox2d
box2d || stringstring
bytes || bytesbytes
bytes || bytes[]bytes[]
bytes[] || bytesbytes[]
bytes[] || bytes[]bytes[]
date || date[]date[]
date || stringstring
date[] || datedate[]
date[] || date[]date[]
decimal || decimal[]decimal[]
decimal || stringstring
decimal[] || decimaldecimal[]
decimal[] || decimal[]decimal[]
float || float[]float[]
float || stringstring
float[] || floatfloat[]
float[] || float[]float[]
geography || geographygeography
geography || stringstring
geometry || geometrygeometry
geometry || stringstring
inet || inet[]inet[]
inet || stringstring
inet[] || inetinet[]
inet[] || inet[]inet[]
int || int[]int[]
int || stringstring
int[] || intint[]
int[] || int[]int[]
interval || interval[]interval[]
interval || stringstring
interval[] || intervalinterval[]
interval[] || interval[]interval[]
jsonb || jsonbjsonb
jsonb || stringstring
oid || oidoid
oid || stringstring
pg_lsn || pg_lsnpg_lsn
pg_lsn || stringstring
refcursor || refcursorrefcursor
refcursor || stringstring
string || boolstring
string || box2dstring
string || datestring
string || decimalstring
string || floatstring
string || geographystring
string || geometrystring
string || inetstring
string || intstring
string || intervalstring
string || jsonbstring
string || oidstring
string || pg_lsnstring
string || refcursorstring
string || stringstring
string || string[]string[]
string || timestring
string || timestampstring
string || timestamptzstring
string || timetzstring
string || tuplestring
string || uuidstring
string || varbitstring
string[] || stringstring[]
string[] || string[]string[]
time || stringstring
time || time[]time[]
time[] || timetime[]
time[] || time[]time[]
timestamp || stringstring
timestamp || timestamp[]timestamp[]
timestamp[] || timestamptimestamp[]
timestamp[] || timestamp[]timestamp[]
timestamptz || stringstring
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timetz || stringstring
timetz || timetztimetz
tuple || stringstring
uuid || stringstring
uuid || uuid[]uuid[]
uuid[] || uuiduuid[]
uuid[] || uuid[]uuid[]
varbit || stringstring
varbit || varbitvarbit
+ + + + + +
||/Return
||/decimaldecimal
||/floatfloat
+ + + + + + + + + + + +
~Return
~inetinet
~intint
~varbitvarbit
box2d ~ box2dbool
box2d ~ geometrybool
geometry ~ box2dbool
geometry ~ geometrybool
string ~ stringbool
+ + + + +
~*Return
string ~* stringbool
diff --git a/src/current/_includes/cockroach-generated/release-24.3/sql/window_functions.md b/src/current/_includes/cockroach-generated/release-24.3/sql/window_functions.md new file mode 100644 index 00000000000..e1032ff82de --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-24.3/sql/window_functions.md @@ -0,0 +1,413 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cume_dist() → float

Calculates the relative rank of the current row: (number of rows preceding or peer with current row) / (total rows).

+		Immutable
dense_rank() → int

Calculates the rank of the current row without gaps; this function counts peer groups.

+		Immutable
first_value(val: bool) → bool

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: bytes) → bytes

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: date) → date

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: decimal) → decimal

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: float) → float

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: inet) → inet

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: int) → int

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: interval) → interval

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: string) → string

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: time) → time

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: uuid) → uuid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: box2d) → box2d

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geography) → geography

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geometry) → geometry

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: oid) → oid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timetz) → timetz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: varbit) → varbit

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
lag(val: bool) → bool

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: bytes) → bytes

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: date) → date

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: date, n: int) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: decimal) → decimal

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: float) → float

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: float, n: int) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: inet) → inet

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: int) → int

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: int, n: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: interval) → interval

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: string) → string

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: string, n: int) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: time) → time

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: time, n: int) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamp) → timestamp

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz) → timestamptz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: uuid) → uuid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: box2d) → box2d

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geography) → geography

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geometry) → geometry

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: jsonb) → jsonb

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: oid) → oid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn) → pg_lsn

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: refcursor) → refcursor

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timetz) → timetz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: varbit) → varbit

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
last_value(val: bool) → bool

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: bytes) → bytes

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: date) → date

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: decimal) → decimal

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: float) → float

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: inet) → inet

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: int) → int

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: interval) → interval

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: string) → string

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: time) → time

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: uuid) → uuid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: box2d) → box2d

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geography) → geography

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geometry) → geometry

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: oid) → oid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timetz) → timetz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: varbit) → varbit

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
lead(val: bool) → bool

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: bytes) → bytes

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: date) → date

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: date, n: int) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: decimal) → decimal

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: float) → float

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: float, n: int) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: inet) → inet

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: int) → int

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: int, n: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: interval) → interval

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: string) → string

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: string, n: int) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: time) → time

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: time, n: int) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamp) → timestamp

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz) → timestamptz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: uuid) → uuid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: box2d) → box2d

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geography) → geography

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geometry) → geometry

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: jsonb) → jsonb

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: oid) → oid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn) → pg_lsn

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: refcursor) → refcursor

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timetz) → timetz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: varbit) → varbit

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
nth_value(val: bool, n: int) → bool

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: bytes, n: int) → bytes

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: date, n: int) → date

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: decimal, n: int) → decimal

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: float, n: int) → float

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: inet, n: int) → inet

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: int, n: int) → int

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: interval, n: int) → interval

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: string, n: int) → string

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: time, n: int) → time

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: uuid, n: int) → uuid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: box2d, n: int) → box2d

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geography, n: int) → geography

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geometry, n: int) → geometry

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: oid, n: int) → oid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timetz, n: int) → timetz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: varbit, n: int) → varbit

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
ntile(n: int) → int

Calculates an integer ranging from 1 to n, dividing the partition as equally as possible.

+		Immutable
percent_rank() → float

Calculates the relative rank of the current row: (rank - 1) / (total rows - 1).

+		Immutable
rank() → int

Calculates the rank of the current row with gaps; same as row_number of its first peer.

+		Immutable
row_number() → int

Calculates the number of the current row within its partition, counting from 1.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-25.1/eventlog.md b/src/current/_includes/cockroach-generated/release-25.1/eventlog.md new file mode 100644 index 00000000000..99bf55ac05d --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.1/eventlog.md @@ -0,0 +1,3436 @@ +Certain notable events are reported using a structured format. +Commonly, these notable events are also copied to the table +`system.eventlog`, unless the cluster setting +`server.eventlog.enabled` is unset. + +Additionally, notable events are copied to specific external logging +channels in log messages, where they can be collected for further processing. + +The sections below document the possible notable event types +in this version of CockroachDB. For each event type, a table +documents the possible fields. A field may be omitted from +an event if its value is empty or zero. + +A field is also considered "Sensitive" if it may contain +application-specific information or personally identifiable information (PII). In that case, +the copy of the event sent to the external logging channel +will contain redaction markers in a format that is compatible +with the redaction facilities in [`cockroach debug zip`](cockroach-debug-zip.html) +and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html), +provided the `redactable` functionality is enabled on the logging sink. + +Events not documented on this page will have an unstructured format in log messages. + +## Changefeed telemetry events + +Events in this category pertain to changefeed usage and metrics. + +Events in this category are logged to the `TELEMETRY` channel. + + +### `changefeed_emitted_bytes` + +An event of type `changefeed_emitted_bytes` is an event representing the bytes emitted by a changefeed over an interval. + + +| Field | Description | Sensitive | +|--|--|--| +| `EmittedBytes` | The number of bytes emitted. | no | +| `EmittedMessages` | The number of messages emitted. | no | +| `LoggingInterval` | The time period in nanoseconds between emitting telemetry events of this type (per-aggregator). | no | +| `Closing` | Flag to indicate that the changefeed is closing. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `changefeed_failed` + +An event of type `changefeed_failed` is an event for any changefeed failure since the plan hook +was triggered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FailureType` | The reason / environment with which the changefeed failed (ex: connection_closed, changefeed_behind). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `create_changefeed` + +An event of type `create_changefeed` is an event for any CREATE CHANGEFEED query that +successfully starts running. Failed CREATE statements will show up as +ChangefeedFailed events. + + +| Field | Description | Sensitive | +|--|--|--| +| `Transformation` | Flag representing whether the changefeed is using CDC queries. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +## Cluster-level events + +Events in this category pertain to an entire cluster and are +not relative to any particular tenant. + +In a multi-tenant setup, the `system.eventlog` table for individual +tenants cannot contain a copy of cluster-level events; conversely, +the `system.eventlog` table in the system tenant cannot contain the +SQL-level events for individual tenants. + +Events in this category are logged to the `OPS` channel. + + +### `certs_reload` + +An event of type `certs_reload` is recorded when the TLS certificates are +reloaded/rotated from disk. + + +| Field | Description | Sensitive | +|--|--|--| +| `Success` | Whether the operation completed without errors. | no | +| `ErrorMessage` | If an error was encountered, the text of the error. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `disk_slowness_cleared` + +An event of type `disk_slowness_cleared` is recorded when disk slowness in a store has cleared. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `disk_slowness_detected` + +An event of type `disk_slowness_detected` is recorded when a store observes disk slowness +events. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `node_decommissioned` + +An event of type `node_decommissioned` is recorded when a node is marked as +decommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_decommissioning` + +An event of type `node_decommissioning` is recorded when a node is marked as +decommissioning. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_join` + +An event of type `node_join` is recorded when a node joins the cluster. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_recommissioned` + +An event of type `node_recommissioned` is recorded when a decommissioning node is +recommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_restart` + +An event of type `node_restart` is recorded when an existing node rejoins the cluster +after being offline. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_connection_timeout` + +An event of type `node_shutdown_connection_timeout` is recorded when SQL connections remain open +during shutdown, after waiting for the server.shutdown.connections.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still open after waiting for the client to close them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.connections.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_transaction_timeout` + +An event of type `node_shutdown_transaction_timeout` is recorded when SQL transactions remain open +during shutdown, after waiting for the server.shutdown.transactions.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still running SQL transactions after waiting for the client to end them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.transactions.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `tenant_shared_service_start` + +An event of type `tenant_shared_service_start` is recorded when a tenant server +is started inside the same process as the KV layer. + + +| Field | Description | Sensitive | +|--|--|--| +| `OK` | Whether the startup was successful. | no | +| `ErrorText` | If the startup failed, the text of the error. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +### `tenant_shared_service_stop` + +An event of type `tenant_shared_service_stop` is recorded when a tenant server +is shut down inside the same process as the KV layer. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +## Debugging events + +Events in this category pertain to debugging operations performed by +operators or (more commonly) Cockroach Labs employees. These operations can +e.g. directly access and mutate internal state, breaking system invariants. + +Events in this category are logged to the `OPS` channel. + + +### `debug_recover_replica` + +An event of type `debug_recover_replica` is recorded when unsafe loss of quorum recovery is performed. + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `StoreID` | | no | +| `SurvivorReplicaID` | | no | +| `UpdatedReplicaID` | | no | +| `StartKey` | | yes | +| `EndKey` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +### `debug_send_kv_batch` + +An event of type `debug_send_kv_batch` is recorded when an arbitrary KV BatchRequest is submitted +to the cluster via the `debug send-kv-batch` CLI command. + + +| Field | Description | Sensitive | +|--|--|--| +| `BatchRequest` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +## Health events + +Events in this category pertain to the health of one or more servers. + +Events in this category are logged to the `HEALTH` channel. + + +### `runtime_stats` + +An event of type `runtime_stats` is recorded every 10 seconds as server health metrics. + + +| Field | Description | Sensitive | +|--|--|--| +| `MemRSSBytes` | The process resident set size. Expressed as bytes. | no | +| `GoroutineCount` | The number of goroutines. | no | +| `MemStackSysBytes` | The stack system memory used. Expressed as bytes. | no | +| `GoAllocBytes` | The memory allocated by Go. Expressed as bytes. | no | +| `GoTotalBytes` | The total memory allocated by Go but not released. Expressed as bytes. | no | +| `GoStatsStaleness` | The staleness of the Go memory statistics. Expressed in seconds. | no | +| `HeapFragmentBytes` | The amount of heap fragmentation. Expressed as bytes. | no | +| `HeapReservedBytes` | The amount of heap reserved. Expressed as bytes. | no | +| `HeapReleasedBytes` | The amount of heap released. Expressed as bytes. | no | +| `CGoAllocBytes` | The memory allocated outside of Go. Expressed as bytes. | no | +| `CGoTotalBytes` | The total memory allocated outside of Go but not released. Expressed as bytes. | no | +| `CGoCallRate` | The total number of calls outside of Go over time. Expressed as operations per second. | no | +| `CPUUserPercent` | The user CPU percentage. | no | +| `CPUSysPercent` | The system CPU percentage. | no | +| `GCPausePercent` | The GC pause percentage. | no | +| `GCRunCount` | The total number of GC runs. | no | +| `NetHostRecvBytes` | The bytes received on all network interfaces since this process started. | no | +| `NetHostSendBytes` | The bytes sent on all network interfaces since this process started. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Job events + +Events in this category pertain to long-running jobs that are orchestrated by +a node's job registry. These system processes can create and/or modify stored +objects during the course of their execution. + +A job might choose to emit multiple events during its execution when +transitioning from one "state" to another. +Egs: IMPORT/RESTORE will emit events on job creation and successful +completion. If the job fails, events will be emitted on job creation, +failure, and successful revert. + +Events in this category are logged to the `OPS` channel. + + +### `import` + +An event of type `import` is recorded when an import job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `restore` + +An event of type `restore` is recorded when a restore job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `status_change` + +An event of type `status_change` is recorded when a job changes statuses. + + +| Field | Description | Sensitive | +|--|--|--| +| `JobID` | The ID of the job that is changing statuses. | no | +| `JobType` | The type of the job that is changing statuses. | no | +| `Description` | A human parsable description of the status change | partially | +| `PreviousStatus` | The status that the job is transitioning out of | no | +| `NewStatus` | The status that the job has transitioned into | no | +| `RunNum` | The run number of the job. | no | +| `Error` | An error that may have occurred while the job was running. | yes | +| `FinalResumeErr` | An error that occurred that requires the job to be reverted. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Miscellaneous SQL events + +Events in this category report miscellaneous SQL events. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own system.eventlog table. + +Events in this category are logged to the `OPS` channel. + + +### `set_cluster_setting` + +An event of type `set_cluster_setting` is recorded when a cluster setting is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `set_tenant_cluster_setting` + +An event of type `set_tenant_cluster_setting` is recorded when a cluster setting override +is changed, either for another tenant or for all tenants. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | +| `TenantId` | The target Tenant ID. Empty if targeting all tenants. | no | +| `AllTenants` | Whether the override applies to all tenants. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +## SQL Access Audit Events + +Events in this category are generated when a table has been +marked as audited via `ALTER TABLE ... EXPERIMENTAL_AUDIT SET`. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SENSITIVE_ACCESS` channel. + + +### `admin_query` + +An event of type `admin_query` is recorded when a user with admin privileges (the user +is directly or indirectly a member of the admin role) executes a query. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `role_based_audit_event` + +An event of type `role_based_audit_event` is an audit event recorded when an executed query belongs to a user whose role +membership(s) correspond to any role that is enabled to emit an audit log via the sql.log.user_audit +cluster setting. + + +| Field | Description | Sensitive | +|--|--|--| +| `Role` | The configured audit role that emitted this log. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sensitive_table_access` + +An event of type `sensitive_table_access` is recorded when an access is performed to +a table marked as audited. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table being audited. | yes | +| `AccessMode` | How the table was accessed (r=read / rw=read/write). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +## SQL Execution Log + +Events in this category report executed queries. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `query_execute` + +An event of type `query_execute` is recorded when a query is executed, +and the cluster setting `sql.log.all_statements.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +## SQL Logical Schema Changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the SQL logical +schema. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SQL_SCHEMA` channel. + + +### `alter_database_add_region` + +An event of type `alter_database_add_region` is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `RegionName` | The region being added. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_drop_region` + +AlterDatabaseAddRegion is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `RegionName` | The region being dropped. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_placement` + +An event of type `alter_database_placement` is recorded when the database placement is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `Placement` | The new placement policy. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_primary_region` + +An event of type `alter_database_primary_region` is recorded when a primary region is added/modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `PrimaryRegionName` | The new primary region. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_set_zone_config_extension` + +An event of type `alter_database_set_zone_config_extension` is recorded when a zone config extension is changed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `alter_database_survival_goal` + +An event of type `alter_database_survival_goal` is recorded when the survival goal is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `SurvivalGoal` | The new survival goal | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_function_options` + +An event of type `alter_function_options` is recorded when a user-defined function's options are +altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the affected function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_index` + +An event of type `alter_index` is recorded when an index is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_index_visible` + +AlterIndex is recorded when an index visibility is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `NotVisible` | Set true if index is not visible. NOTE: THIS FIELD IS DEPRECATED in favor of invisibility. | no | +| `Invisibility` | The new invisibility of the affected index. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_sequence` + +An event of type `alter_sequence` is recorded when a sequence is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_table` + +An event of type `alter_table` is recorded when a table is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update, if any. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_type` + +EventAlterType is recorded when a user-defined type is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_column` + +An event of type `comment_on_column` is recorded when a column is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected column. | no | +| `ColumnName` | The affected column. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_constraint` + +An event of type `comment_on_constraint` is recorded when an constraint is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected constraint. | no | +| `ConstraintName` | The name of the affected constraint. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_database` + +CommentOnTable is recorded when a database is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_index` + +An event of type `comment_on_index` is recorded when an index is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_schema` + + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | Name of the affected schema. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_table` + +An event of type `comment_on_table` is recorded when a table is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_type` + +An event of type `comment_on_type` is recorded when a type is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_database` + +An event of type `create_database` is recorded when a database is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the new database. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_function` + +An event of type `create_function` is recorded when a user-defined function is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the created function. | no | +| `IsReplace` | If the new function is a replace of an existing function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_index` + +An event of type `create_index` is recorded when an index is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the new index. | no | +| `IndexName` | The name of the new index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_schema` + +An event of type `create_schema` is recorded when a schema is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the new schema. | no | +| `Owner` | The name of the owner for the new schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_sequence` + +An event of type `create_sequence` is recorded when a sequence is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the new sequence. | no | +| `Owner` | The name of the owner for the new sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_statistics` + +An event of type `create_statistics` is recorded when statistics are collected for a +table. + +Events of this type are only collected when the cluster setting +`sql.stats.post_events.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table for which the statistics were created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_table` + +An event of type `create_table` is recorded when a table is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the new table. | no | +| `Owner` | The name of the owner for the new table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_trigger` + +An event of type `create_trigger` is recorded when a trigger is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the trigger's table. | no | +| `TriggerName` | Name of the created trigger. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_type` + +An event of type `create_type` is recorded when a user-defined type is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the new type. | no | +| `Owner` | The name of the owner for the new type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_view` + +An event of type `create_view` is recorded when a view is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the new view. | no | +| `Owner` | The name of the owner of the new view. | no | +| `ViewQuery` | The SQL selection clause used to define the view. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_database` + +An event of type `drop_database` is recorded when a database is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | no | +| `DroppedSchemaObjects` | The names of the schemas dropped by a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_function` + +An event of type `drop_function` is recorded when a user-defined function is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the dropped function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_index` + +An event of type `drop_index` is recorded when an index is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_schema` + +An event of type `drop_schema` is recorded when a schema is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_sequence` + +An event of type `drop_sequence` is recorded when a sequence is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_table` + +An event of type `drop_table` is recorded when a table is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_trigger` + +An event of type `drop_trigger` is recorded when a trigger is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the trigger's table. | no | +| `TriggerName` | Name of the dropped trigger. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_type` + +An event of type `drop_type` is recorded when a user-defined type is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_view` + +An event of type `drop_view` is recorded when a view is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the affected view. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `finish_schema_change` + +An event of type `finish_schema_change` is recorded when a previously initiated schema +change has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to complete. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `finish_schema_change_rollback` + +An event of type `finish_schema_change_rollback` is recorded when a previously +initiated schema change rollback has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to rollback. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `force_delete_table_data_entry` + + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_database` + +An event of type `rename_database` is recorded when a database is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The old name of the affected database. | no | +| `NewDatabaseName` | The new name of the affected database. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_function` + +An event of type `rename_function` is recorded when a user-defined function is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The old name of the affected function. | no | +| `NewFunctionName` | The new name of the affected function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_schema` + +An event of type `rename_schema` is recorded when a schema is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The old name of the affected schema. | no | +| `NewSchemaName` | The new name of the affected schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_table` + +An event of type `rename_table` is recorded when a table, sequence or view is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The old name of the affected table. | no | +| `NewTableName` | The new name of the affected table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_type` + +An event of type `rename_type` is recorded when a user-defined type is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The old name of the affected type. | no | +| `NewTypeName` | The new name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `reverse_schema_change` + +An event of type `reverse_schema_change` is recorded when an in-progress schema change +encounters a problem and is reversed. + + +| Field | Description | Sensitive | +|--|--|--| +| `Error` | The error encountered that caused the schema change to be reversed. The specific format of the error is variable and can change across releases without warning. | partially | +| `SQLSTATE` | The SQLSTATE code for the error. | no | +| `LatencyNanos` | The amount of time the schema change job took before being reverted. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `set_schema` + +An event of type `set_schema` is recorded when a table, view, sequence or type's schema is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorName` | The old name of the affected descriptor. | no | +| `NewDescriptorName` | The new name of the affected descriptor. | no | +| `DescriptorType` | The descriptor type being changed (table, view, sequence, type). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `truncate_table` + +An event of type `truncate_table` is recorded when a table is truncated. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_delete_descriptor` + +An event of type `unsafe_delete_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_delete_descriptor(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_delete_namespace_entry` + +An event of type `unsafe_delete_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_delete_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_upsert_descriptor` + +An event of type `unsafe_upsert_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_upsert_descriptor(). + + +| Field | Description | Sensitive | +|--|--|--| +| `PreviousDescriptor` | | yes | +| `NewDescriptor` | | yes | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_upsert_namespace_entry` + +An event of type `unsafe_upsert_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_upsert_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `PreviousID` | | no | +| `Force` | | no | +| `FailedValidation` | | no | +| `ValidationErrors` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +## SQL Privilege changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the privilege +grants for stored objects. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `PRIVILEGES` channel. + + +### `alter_database_owner` + +An event of type `alter_database_owner` is recorded when a database's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database being affected. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_default_privileges` + +An event of type `alter_default_privileges` is recorded when default privileges are changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | +| `RoleName` | Either role_name should be populated or for_all_roles should be true. The role having its default privileges altered. | yes | +| `ForAllRoles` | Identifies if FOR ALL ROLES is used. | no | +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `alter_function_owner` + +AlterTableOwner is recorded when the owner of a user-defined function is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The name of the affected user-defined function. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_schema_owner` + +An event of type `alter_schema_owner` is recorded when a schema's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_table_owner` + +An event of type `alter_table_owner` is recorded when the owner of a table, view or sequence is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected object. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_type_owner` + +An event of type `alter_type_owner` is recorded when the owner of a user-defiend type is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `change_database_privilege` + +An event of type `change_database_privilege` is recorded when privileges are +added to / removed from a user for a database object. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_function_privilege` + + + +| Field | Description | Sensitive | +|--|--|--| +| `FuncName` | The name of the affected function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_schema_privilege` + +An event of type `change_schema_privilege` is recorded when privileges are added to / +removed from a user for a schema object. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_table_privilege` + +An event of type `change_table_privilege` is recorded when privileges are added to / removed +from a user for a table, sequence or view object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_type_privilege` + +An event of type `change_type_privilege` is recorded when privileges are added to / +removed from a user for a type object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +## SQL Session events + +Events in this category report SQL client connections +and sessions. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SESSIONS` channel. + + +### `client_authentication_failed` + +An event of type `client_authentication_failed` is reported when a client session +did not authenticate successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Reason` | The reason for the authentication failure. See below for possible values for type `AuthFailReason`. | no | +| `Detail` | The detailed error for the authentication failure. | partially | +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_info` + +An event of type `client_authentication_info` is reported for intermediate +steps during the authentication process. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used, once known. | no | +| `Info` | The authentication progress message. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_ok` + +An event of type `client_authentication_ok` is reported when a client session +was authenticated successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_connection_end` + +An event of type `client_connection_end` is reported when a client connection +is closed. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_connection_start` + +An event of type `client_connection_start` is reported when a client connection +is established. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_session_end` + +An event of type `client_session_end` is reported when a client session +is completed. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +## SQL Slow Query Log + +Events in this category report slow query execution. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_PERF` channel. + + +### `large_row` + +An event of type `large_row` is recorded when a statement tries to write a row larger than +cluster setting `sql.guardrails.max_row_size_log` to the database. Multiple +LargeRow events will be recorded for statements writing multiple large rows. +LargeRow events are recorded before the transaction commits, so in the case +of transaction abort there will not be a corresponding row in the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query` + +An event of type `slow_query` is recorded when a query triggers the "slow query" condition. + +As of this writing, the condition requires: +- the cluster setting `sql.log.slow_query.latency_threshold` +set to a non-zero value, AND +- EITHER of the following conditions: +- the actual age of the query exceeds the configured threshold; AND/OR +- the query performs a full table/index scan AND the cluster setting +`sql.log.slow_query.experimental_full_table_scans.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit` + +An event of type `txn_rows_read_limit` is recorded when a transaction tries to read more rows than +cluster setting `sql.defaults.transaction_rows_read_log`. There will only be +a single record for a single transaction (unless it is retried) even if there +are more statement within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit` + +An event of type `txn_rows_written_limit` is recorded when a transaction tries to write more rows +than cluster setting `sql.defaults.transaction_rows_written_log`. There will +only be a single record for a single transaction (unless it is retried) even +if there are more mutation statements within the transaction that haven't +been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL Slow Query Log (Internal) + +Events in this category report slow query execution by +internal executors, i.e., when CockroachDB internally issues +SQL statements. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_INTERNAL_PERF` channel. + + +### `large_row_internal` + +An event of type `large_row_internal` is recorded when an internal query tries to write a row +larger than cluster settings `sql.guardrails.max_row_size_log` or +`sql.guardrails.max_row_size_err` to the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query_internal` + +An event of type `slow_query_internal` is recorded when a query triggers the "slow query" condition, +and the cluster setting `sql.log.slow_query.internal_queries.enabled` is +set. +See the documentation for the event type `slow_query` for details about +the "slow query" condition. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit_internal` + +An event of type `txn_rows_read_limit_internal` is recorded when an internal transaction tries to +read more rows than cluster setting `sql.defaults.transaction_rows_read_log` +or `sql.defaults.transaction_rows_read_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit_internal` + +An event of type `txn_rows_written_limit_internal` is recorded when an internal transaction tries to +write more rows than cluster setting +`sql.defaults.transaction_rows_written_log` or +`sql.defaults.transaction_rows_written_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL User and Role operations + +Events in this category pertain to SQL statements that modify the +properties of users and roles. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `USER_ADMIN` channel. + + +### `alter_role` + +An event of type `alter_role` is recorded when a role is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | +| `Options` | The options set on the user/role. | no | +| `SetInfo` | Information corresponding to an ALTER ROLE SET statement. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_role` + +An event of type `create_role` is recorded when a role is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the new user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_role` + +An event of type `drop_role` is recorded when a role is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `grant_role` + +An event of type `grant_role` is recorded when a role is granted. + + +| Field | Description | Sensitive | +|--|--|--| +| `GranteeRoles` | The roles being granted to. | yes | +| `Members` | The roles being granted. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `password_hash_converted` + +An event of type `password_hash_converted` is recorded when the password credentials +are automatically converted server-side. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the user/role whose credentials have been converted. | yes | +| `OldMethod` | The previous hash method. | no | +| `NewMethod` | The new hash method. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Storage telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `level_stats` + +An event of type `level_stats` contains per-level statistics for an LSM. + + +| Field | Description | Sensitive | +|--|--|--| +| `Level` | level is the level ID in a LSM (e.g. level(L0) == 0, etc.) | no | +| `NumFiles` | num_files is the number of files in the level (gauge). | no | +| `SizeBytes` | size_bytes is the size of the level, in bytes (gauge). | no | +| `Score` | score is the compaction score of the level (gauge). | no | +| `BytesIn` | bytes_in is the number of bytes written to this level (counter). | no | +| `BytesIngested` | bytes_ingested is the number of bytes ingested into this level (counter). | no | +| `BytesMoved` | bytes_moved is the number of bytes moved into this level via a move-compaction (counter). | no | +| `BytesRead` | bytes_read is the number of bytes read from this level, during compactions (counter). | no | +| `BytesCompacted` | bytes_compacted is the number of bytes written to this level during compactions (counter). | no | +| `BytesFlushed` | bytes flushed is the number of bytes flushed to this level. This value is always zero for levels other than L0 (counter). | no | +| `TablesCompacted` | tables_compacted is the count of tables compacted into this level (counter). | no | +| `TablesFlushed` | tables_flushed is the count of tables flushed into this level (counter). | no | +| `TablesIngested` | tables_ingested is the count of tables ingested into this level (counter). | no | +| `TablesMoved` | tables_moved is the count of tables moved into this level via move-compactions (counter). | no | +| `NumSublevels` | num_sublevel is the count of sublevels for the level. This value is always zero for levels other than L0 (gauge). | no | + + + +### `store_stats` + +An event of type `store_stats` contains per store stats. + +Note that because stats are scoped to the lifetime of the process, counters +(and certain gauges) will be reset across node restarts. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeId` | node_id is the ID of the node. | no | +| `StoreId` | store_id is the ID of the store. | no | +| `Levels` | levels is a nested message containing per-level statistics. | yes | +| `CacheSize` | cache_size is the size of the cache for the store, in bytes (gauge). | no | +| `CacheCount` | cache_count is the number of items in the cache (gauge). | no | +| `CacheHits` | cache_hits is the number of cache hits (counter). | no | +| `CacheMisses` | cache_misses is the number of cache misses (counter). | no | +| `CompactionCountDefault` | compaction_count_default is the count of default compactions (counter). | no | +| `CompactionCountDeleteOnly` | compaction_count_delete_only is the count of delete-only compactions (counter). | no | +| `CompactionCountElisionOnly` | compaction_count_elision_only is the count of elision-only compactions (counter). | no | +| `CompactionCountMove` | compaction_count_move is the count of move-compactions (counter). | no | +| `CompactionCountRead` | compaction_count_read is the count of read-compactions (counter). | no | +| `CompactionCountRewrite` | compaction_count_rewrite is the count of rewrite-compactions (counter). | no | +| `CompactionNumInProgress` | compactions_num_in_progress is the number of compactions in progress (gauge). | no | +| `CompactionMarkedFiles` | compaction_marked_files is the count of files marked for compaction (gauge). | no | +| `FlushCount` | flush_count is the number of flushes (counter). | no | +| `FlushIngestCount` | | no | +| `FlushIngestTableCount` | | no | +| `FlushIngestTableBytes` | | no | +| `IngestCount` | ingest_count is the number of successful ingest operations (counter). | no | +| `MemtableSize` | memtable_size is the total size allocated to all memtables and (large) batches, in bytes (gauge). | no | +| `MemtableCount` | memtable_count is the count of memtables (gauge). | no | +| `MemtableZombieCount` | memtable_zombie_count is the count of memtables no longer referenced by the current DB state, but still in use by an iterator (gauge). | no | +| `MemtableZombieSize` | memtable_zombie_size is the size, in bytes, of all zombie memtables (gauge). | no | +| `WalLiveCount` | wal_live_count is the count of live WAL files (gauge). | no | +| `WalLiveSize` | wal_live_size is the size, in bytes, of live data in WAL files. With WAL recycling, this value is less than the actual on-disk size of the WAL files (gauge). | no | +| `WalObsoleteCount` | wal_obsolete_count is the count of obsolete WAL files (gauge). | no | +| `WalObsoleteSize` | wal_obsolete_size is the size of obsolete WAL files, in bytes (gauge). | no | +| `WalPhysicalSize` | wal_physical_size is the size, in bytes, of the WAL files on disk (gauge). | no | +| `WalBytesIn` | wal_bytes_in is the number of logical bytes written to the WAL (counter). | no | +| `WalBytesWritten` | wal_bytes_written is the number of bytes written to the WAL (counter). | no | +| `TableObsoleteCount` | table_obsolete_count is the number of tables which are no longer referenced by the current DB state or any open iterators (gauge). | no | +| `TableObsoleteSize` | table_obsolete_size is the size, in bytes, of obsolete tables (gauge). | no | +| `TableZombieCount` | table_zombie_count is the number of tables no longer referenced by the current DB state, but are still in use by an open iterator (gauge). | no | +| `TableZombieSize` | table_zombie_size is the size, in bytes, of zombie tables (gauge). | no | +| `RangeKeySetsCount` | range_key_sets_count is the approximate count of internal range key sets in the store. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `captured_index_usage_stats` + +An event of type `captured_index_usage_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `TotalReadCount` | TotalReadCount is the number of times the index has been read. | no | +| `LastRead` | LastRead is the timestamp at which the index was last read. | no | +| `TableID` | TableID is the ID of the table on which the index was created. This is same as descpb.TableID and is unique within the cluster. | no | +| `IndexID` | IndexID is the ID of the index within the scope of the given table. | no | +| `DatabaseName` | DatabaseName is the name of the database in which the index was created. | no | +| `TableName` | TableName is the name of the table on which the index was created. | no | +| `IndexName` | IndexName is the name of the index within the scope of the given table. | no | +| `IndexType` | IndexType is the type of the index. Index types include "primary" and "secondary". | no | +| `IsUnique` | IsUnique indicates if the index has a UNIQUE constraint. | no | +| `IsInverted` | IsInverted indicates if the index is an inverted index. | no | +| `CreatedAt` | CreatedAt is the timestamp at which the index was created. | no | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `hot_ranges_stats` + +An event of type `hot_ranges_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `Qps` | | no | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | yes | +| `LeaseholderNodeID` | LeaseholderNodeID indicates the Node ID that is the current leaseholder for the given range. | no | +| `WritesPerSecond` | Writes per second is the recent number of keys written per second on this range. | no | +| `ReadsPerSecond` | Reads per second is the recent number of keys read per second on this range. | no | +| `WriteBytesPerSecond` | Write bytes per second is the recent number of bytes written per second on this range. | no | +| `ReadBytesPerSecond` | Read bytes per second is the recent number of bytes read per second on this range. | no | +| `CPUTimePerSecond` | CPU time per second is the recent cpu usage in nanoseconds of this range. | no | +| `Databases` | Databases for the range. | yes | +| `Tables` | Tables for the range | yes | +| `Indexes` | Indexes for the range | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `m_v_c_c_iterator_stats` + +Internal storage iteration statistics for a single execution. + + +| Field | Description | Sensitive | +|--|--|--| +| `StepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `StepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `BlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `BlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `KeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `ValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | + + + +### `recovery_event` + +An event of type `recovery_event` is an event that is logged on every invocation of BACKUP, +RESTORE, and on every BACKUP schedule creation, with the appropriate subset +of fields populated depending on the type of event. This event is is also +logged whenever a BACKUP and RESTORE job completes or fails. + + +| Field | Description | Sensitive | +|--|--|--| +| `RecoveryType` | RecoveryType is the type of recovery described by this event, which is one of - backup - scheduled_backup - create_schedule - restore

It can also be a job event corresponding to the recovery, which is one of - backup_job - scheduled_backup_job - restore_job | no | +| `TargetScope` | TargetScope is the largest scope of the targets that the user is backing up or restoring based on the following order: table < schema < database < full cluster. | no | +| `IsMultiregionTarget` | IsMultiregionTarget is true if any of the targets contain objects with multi-region primitives. | no | +| `TargetCount` | TargetCount is the number of targets the in the BACKUP/RESTORE. | no | +| `DestinationSubdirType` | DestinationSubdirType is - latest: if using the latest subdir - standard: if using a date-based subdir - custom: if using a custom subdir that's not date-based | no | +| `DestinationStorageTypes` | DestinationStorageTypes are the types of storage that the user is backing up to or restoring from. | no | +| `DestinationAuthTypes` | DestinationAuthTypes are the types of authentication methods that the user is using to access the destination storage. | no | +| `IsLocalityAware` | IsLocalityAware indicates if the BACKUP or RESTORE is locality aware. | no | +| `AsOfInterval` | AsOfInterval is the time interval in nanoseconds between the statement timestamp and the timestamp resolved by the AS OF SYSTEM TIME expression. The interval is expressed in nanoseconds. | no | +| `WithRevisionHistory` | WithRevisionHistory is true if the BACKUP includes revision history. | no | +| `HasEncryptionPassphrase` | HasEncryptionPassphrase is true if the user provided an encryption passphrase to encrypt/decrypt their backup. | no | +| `KMSType` | KMSType is the type of KMS the user is using to encrypt/decrypt their backup. | no | +| `KMSCount` | KMSCount is the number of KMS the user is using. | no | +| `Options` | Options contain all the names of the options specified by the user in the BACKUP or RESTORE statement. For options that are accompanied by a value, only those with non-empty values will be present.

It's important to note that there are no option values anywhere in the event payload. Future changes to telemetry should refrain from adding values to the payload unless they are properly redacted. | no | +| `DebugPauseOn` | DebugPauseOn is the type of event that the restore should pause on for debugging purposes. Currently only "error" is supported. | no | +| `JobID` | JobID is the ID of the BACKUP/RESTORE job. | no | +| `ResultStatus` | ResultStatus indicates whether the job succeeded or failed. | no | +| `ErrorText` | ErrorText is the text of the error that caused the job to fail. | partially | +| `RecurringCron` | RecurringCron is the crontab for the incremental backup. | no | +| `FullBackupCron` | FullBackupCron is the crontab for the full backup. | no | +| `CustomFirstRunTime` | CustomFirstRunTime is the timestamp for the user configured first run time. Expressed as nanoseconds since the Unix epoch. | no | +| `OnExecutionFailure` | OnExecutionFailure describes the desired behavior if the schedule fails to execute. | no | +| `OnPreviousRunning` | OnPreviousRunning describes the desired behavior if the previously scheduled BACKUP is still running. | no | +| `IgnoreExistingBackup` | IgnoreExistingBackup is true iff the BACKUP schedule should still be created even if a backup is already present in its destination. | no | +| `ApplicationName` | The application name for the session where recovery event was created. | no | +| `NumRows` | NumRows is the number of rows successfully imported, backed up or restored. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `sampled_exec_stats` + +An event of type `sampled_exec_stats` contains execution statistics that apply to both statements +and transactions. These stats as a whole are collected using a sampling approach. +These exec stats are meant to contain the same fields as ExecStats in +apps_stats.proto but are for a single execution rather than aggregated executions. +Fields in this struct should be updated in sync with apps_stats.proto. + + +| Field | Description | Sensitive | +|--|--|--| +| `NetworkBytes` | NetworkBytes collects the number of bytes sent over the network. | no | +| `MaxMemUsage` | MaxMemUsage collects the maximum memory usage that occurred on a node. | no | +| `ContentionTime` | ContentionTime collects the time in seconds statements in the transaction spent contending. | no | +| `NetworkMessages` | NetworkMessages collects the number of messages that were sent over the network. | no | +| `MaxDiskUsage` | MaxDiskUsage collects the maximum temporary disk usage that occurred. This is set in cases where a query had to spill to disk, e.g. when performing a large sort where not all of the tuples fit in memory. | no | +| `CPUSQLNanos` | CPUSQLNanos collects the CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `MVCCIteratorStats` | Internal storage iteration statistics. | yes | + + + +### `sampled_query` + +An event of type `sampled_query` is the SQL query event logged to the telemetry channel. It +contains common SQL event/execution details. + + +| Field | Description | Sensitive | +|--|--|--| +| `SkippedQueries` | skipped_queries indicate how many SQL statements were not considered for sampling prior to this one. If the field is omitted, or its value is zero, this indicates that no statement was omitted since the last event. | no | +| `CostEstimate` | Cost of the query as estimated by the optimizer. | no | +| `Distribution` | The distribution of the DistSQL query plan (local, full, or partial). | no | +| `PlanGist` | The query's plan gist bytes as a base64 encoded string. | no | +| `SessionID` | SessionID is the ID of the session that initiated the query. | no | +| `Database` | Name of the database that initiated the query. | no | +| `StatementID` | Statement ID of the query. | no | +| `TransactionID` | Transaction ID of the query. | no | +| `MaxFullScanRowsEstimate` | Maximum number of rows scanned by a full scan, as estimated by the optimizer. | no | +| `TotalScanRowsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer. | no | +| `OutputRowsEstimate` | The number of rows output by the query, as estimated by the optimizer. | no | +| `StatsAvailable` | Whether table statistics were available to the optimizer when planning the query. | no | +| `NanosSinceStatsCollected` | The maximum number of nanoseconds that have passed since stats were collected on any table scanned by this query. | no | +| `BytesRead` | The number of bytes read from disk. | no | +| `RowsRead` | The number of rows read from disk. | no | +| `RowsWritten` | The number of rows written. | no | +| `InnerJoinCount` | The number of inner joins in the query plan. | no | +| `LeftOuterJoinCount` | The number of left (or right) outer joins in the query plan. | no | +| `FullOuterJoinCount` | The number of full outer joins in the query plan. | no | +| `SemiJoinCount` | The number of semi joins in the query plan. | no | +| `AntiJoinCount` | The number of anti joins in the query plan. | no | +| `IntersectAllJoinCount` | The number of intersect all joins in the query plan. | no | +| `ExceptAllJoinCount` | The number of except all joins in the query plan. | no | +| `HashJoinCount` | The number of hash joins in the query plan. | no | +| `CrossJoinCount` | The number of cross joins in the query plan. | no | +| `IndexJoinCount` | The number of index joins in the query plan. | no | +| `LookupJoinCount` | The number of lookup joins in the query plan. | no | +| `MergeJoinCount` | The number of merge joins in the query plan. | no | +| `InvertedJoinCount` | The number of inverted joins in the query plan. | no | +| `ApplyJoinCount` | The number of apply joins in the query plan. | no | +| `ZigZagJoinCount` | The number of zig zag joins in the query plan. | no | +| `ContentionNanos` | The duration of time in nanoseconds that the query experienced contention. | no | +| `Regions` | The regions of the nodes where SQL processors ran. | no | +| `NetworkBytesSent` | The number of network bytes sent by nodes for this query. | no | +| `MaxMemUsage` | The maximum amount of memory usage by nodes for this query. | no | +| `MaxDiskUsage` | The maximum amount of disk usage by nodes for this query. | no | +| `KVBytesRead` | The number of bytes read at the KV layer for this query. | no | +| `KVPairsRead` | The number of key-value pairs read at the KV layer for this query. | no | +| `KVRowsRead` | The number of rows read at the KV layer for this query. | no | +| `NetworkMessages` | The number of network messages sent by nodes for this query. | no | +| `IndexRecommendations` | Generated index recommendations for this query. | no | +| `ScanCount` | The number of scans in the query plan. | no | +| `ScanWithStatsCount` | The number of scans using statistics (including forecasted statistics) in the query plan. | no | +| `ScanWithStatsForecastCount` | The number of scans using forecasted statistics in the query plan. | no | +| `TotalScanRowsWithoutForecastsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer without using forecasts. | no | +| `NanosSinceStatsForecasted` | The greatest quantity of nanoseconds that have passed since the forecast time (or until the forecast time, if it is in the future, in which case it will be negative) for any table with forecasted stats scanned by this query. | no | +| `Indexes` | The list of indexes used by this query. | no | +| `CpuTimeNanos` | Collects the cumulative CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `KvGrpcCalls` | The number of grpc calls done to get data form KV nodes | no | +| `KvTimeNanos` | Cumulated time spent waiting for a KV request. This includes disk IO time and potentially network time (if any of the keys are not local). | no | +| `ServiceLatencyNanos` | The time to service the query, from start of parse to end of execute. | no | +| `OverheadLatencyNanos` | The difference between service latency and the sum of parse latency + plan latency + run latency . | no | +| `RunLatencyNanos` | The time to run the query and fetch or compute the result rows. | no | +| `PlanLatencyNanos` | The time to transform the AST into a logical query plan. | no | +| `IdleLatencyNanos` | The time between statement executions in a transaction | no | +| `ParseLatencyNanos` | The time to transform the SQL string into an abstract syntax tree (AST). | no | +| `MvccStepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccStepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccBlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `MvccBlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `MvccKeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `SchemaChangerMode` | SchemaChangerMode is the mode that was used to execute the schema change, if any. | no | +| `SQLInstanceIDs` | SQLInstanceIDs is a list of all the SQL instances used in this statement's execution. | no | +| `KVNodeIDs` | KVNodeIDs is a list of all the KV nodes used in this statement's execution. | no | +| `StatementFingerprintID` | Statement fingerprint ID of the query. | no | +| `UsedFollowerRead` | UsedFollowerRead indicates whether at least some reads were served by the follower replicas. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sampled_transaction` + +An event of type `sampled_transaction` is the event logged to telemetry at the end of transaction execution. + + +| Field | Description | Sensitive | +|--|--|--| +| `User` | User is the user account that triggered the transaction. The special usernames `root` and `node` are not considered sensitive. | depends | +| `ApplicationName` | ApplicationName is the application name for the session where the transaction was executed. This is included in the event to ease filtering of logging output by application. | no | +| `TxnCounter` | TxnCounter is the sequence number of the SQL transaction inside its session. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `TransactionID` | TransactionID is the id of the transaction. | no | +| `Committed` | Committed indicates if the transaction committed successfully. We want to include this value even if it is false. | no | +| `ImplicitTxn` | ImplicitTxn indicates if the transaction was an implicit one. We want to include this value even if it is false. | no | +| `StartTimeUnixNanos` | StartTimeUnixNanos is the time the transaction was started. Expressed as unix time in nanoseconds. | no | +| `EndTimeUnixNanos` | EndTimeUnixNanos the time the transaction finished (either committed or aborted). Expressed as unix time in nanoseconds. | no | +| `ServiceLatNanos` | ServiceLatNanos is the time to service the whole transaction, from start to end of execution. | no | +| `SQLSTATE` | SQLSTATE is the SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | ErrorText is the text of the error if any. | partially | +| `NumRetries` | NumRetries is the number of time when the txn was retried automatically by the server. | no | +| `LastAutoRetryReason` | LastAutoRetryReason is a string containing the reason for the last automatic retry. | partially | +| `NumRows` | NumRows is the total number of rows returned across all statements. | no | +| `RetryLatNanos` | RetryLatNanos is the amount of time spent retrying the transaction. | no | +| `CommitLatNanos` | CommitLatNanos is the amount of time spent committing the transaction after all statement operations. | no | +| `IdleLatNanos` | IdleLatNanos is the amount of time spent waiting for the client to send statements while the transaction is open. | no | +| `BytesRead` | BytesRead is the number of bytes read from disk. | no | +| `RowsRead` | RowsRead is the number of rows read from disk. | no | +| `RowsWritten` | RowsWritten is the number of rows written to disk. | no | +| `SampledExecStats` | SampledExecStats is a nested field containing execution statistics. This field will be omitted if the stats were not sampled. | yes | +| `SkippedTransactions` | SkippedTransactions is the number of transactions that were skipped as part of sampling prior to this one. We only count skipped transactions when telemetry logging is enabled and the sampling mode is set to "transaction". | no | +| `TransactionFingerprintID` | TransactionFingerprintID is the fingerprint ID of the transaction. This can be used to find the transaction in the console. | no | +| `StatementFingerprintIDs` | StatementFingerprintIDs is an array of statement fingerprint IDs belonging to this transaction. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_descriptor` + +An event of type `schema_descriptor` is an event for schema telemetry, whose purpose is +to take periodic snapshots of the cluster's SQL schema and publish them in +the telemetry log channel. For all intents and purposes, the data in such a +snapshot can be thought of the outer join of certain system tables: +namespace, descriptor, and at some point perhaps zones, etc. + +Snapshots are too large to conveniently be published as a single log event, +so instead they're broken down into SchemaDescriptor events which +contain the data in one record of this outer join projection. These events +are prefixed by a header (a SchemaSnapshotMetadata event). + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of the snapshot that this event is part of. | no | +| `ParentDatabaseID` | ParentDatabaseID matches the same key column in system.namespace. | no | +| `ParentSchemaID` | ParentSchemaID matches the same key column in system.namespace. | no | +| `Name` | Name matches the same key column in system.namespace. | no | +| `DescID` | DescID matches the 'id' column in system.namespace and system.descriptor. | no | +| `Desc` | Desc matches the 'descriptor' column in system.descriptor. Some contents of the descriptor may be redacted to prevent leaking PII. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_snapshot_metadata` + +An event of type `schema_snapshot_metadata` is an event describing a schema snapshot, which +is a set of SchemaDescriptor messages sharing the same SnapshotID. + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of this snapshot. | no | +| `NumRecords` | NumRecords is how many SchemaDescriptor events are in the snapshot. | no | +| `AsOfTimestamp` | AsOfTimestamp is when the snapshot was taken. This is equivalent to the timestamp given in the AS OF SYSTEM TIME clause when querying the namespace and descriptor tables in the system database. Expressed as nanoseconds since the Unix epoch. | no | +| `Errors` | Errors records any errors encountered when post-processing this snapshot, which includes the redaction of any potential PII. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Zone config events + +Events in this category pertain to zone configuration changes on +the SQL schema or system ranges. + +When zone configs apply to individual tables or other objects in a +SQL logical schema, they are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these zone config events are preserved +in each tenant's own `system.eventlog` table. + +When they apply to cluster-level ranges (e.g., the system zone config), +they are stored in the system tenant's own `system.eventlog` table. + +Events in this category are logged to the `OPS` channel. + + +### `remove_zone_config` + +An event of type `remove_zone_config` is recorded when a zone config is removed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `set_zone_config` + +An event of type `set_zone_config` is recorded when a zone config is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `ResolvedOldConfig` | The string representation of the resolved old zone config. This is not necessarily the same as the zone config that was previously set -- as it includes the resolved values of the zone config options. In other words, a zone config that hasn't been properly "set" yet (and inherits from its parent) will have a resolved_old_config that has details of the values it inherits from its parent. This is particularly useful to get a proper diff between the old and new zone config. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + + + + +## Enumeration types + +### `AuthFailReason` + +AuthFailReason is the inventory of possible reasons for an +authentication failure. + + +| Value | Textual alias in code or documentation | Description | +|--|--|--| +| 0 | UNKNOWN | is reported when the reason is unknown. | +| 1 | USER_RETRIEVAL_ERROR | occurs when there was an internal error accessing the principals. | +| 2 | USER_NOT_FOUND | occurs when the principal is unknown. | +| 3 | LOGIN_DISABLED | occurs when the user does not have LOGIN privileges. | +| 4 | METHOD_NOT_FOUND | occurs when no HBA rule matches or the method does not exist. | +| 5 | PRE_HOOK_ERROR | occurs when the authentication handshake encountered a protocol error. | +| 6 | CREDENTIALS_INVALID | occurs when the client-provided credentials were invalid. | +| 7 | CREDENTIALS_EXPIRED | occur when the credentials provided by the client are expired. | +| 8 | NO_REPLICATION_ROLEOPTION | occurs when the connection requires a replication role option, but the user does not have it. | +| 9 | AUTHORIZATION_ERROR | is used for errors during the authorization phase. For example, this would include issues with mapping LDAP groups to SQL roles and granting those roles to the user. | + + + diff --git a/src/current/_includes/cockroach-generated/release-25.1/logformats.md b/src/current/_includes/cockroach-generated/release-25.1/logformats.md new file mode 100644 index 00000000000..89580c9fc15 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.1/logformats.md @@ -0,0 +1,382 @@ + +The supported log output formats are documented below. + + +- [`crdb-v1`](#format-crdb-v1) + +- [`crdb-v1-count`](#format-crdb-v1-count) + +- [`crdb-v1-tty`](#format-crdb-v1-tty) + +- [`crdb-v1-tty-count`](#format-crdb-v1-tty-count) + +- [`crdb-v2`](#format-crdb-v2) + +- [`crdb-v2-tty`](#format-crdb-v2-tty) + +- [`json`](#format-json) + +- [`json-compact`](#format-json-compact) + +- [`json-fluent`](#format-json-fluent) + +- [`json-fluent-compact`](#format-json-fluent-compact) + + + +## Format `crdb-v1` + + +This is a legacy file format used from CockroachDB v1.0. + +Each log entry is emitted using a common prefix, described below, followed by: + +- The logging context tags enclosed between `[` and `]`, if any. It is possible + for this to be omitted if there were no context tags. +- Optionally, a counter column, if the option 'show-counter' is enabled. See below for details. +- the text of the log entry. + +Beware that the text of the log entry can span multiple lines. +The following caveats apply: + +- The text of the log entry can start with text enclosed between `[` and `]`. + If there were no logging tags to start with, it is not possible to distinguish between + logging context tag information and a `[...]` string in the main text of the + log entry. This means that this format is ambiguous. + + To remove this ambiguity, you can use the option 'show-counter'. + +- The text of the log entry can embed arbitrary application-level strings, + including strings that represent log entries. In particular, an accident + of implementation can cause the common entry prefix (described below) + to also appear on a line of its own, as part of the payload of a previous + log entry. There is no automated way to recognize when this occurs. + Care must be taken by a human observer to recognize these situations. + +- The log entry parser provided by CockroachDB to read log files is faulty + and is unable to recognize the aforementioned pitfall; nor can it read + entries larger than 64KiB successfully. Generally, use of this internal + log entry parser is discouraged for entries written with this format. + +See the newer format `crdb-v2` for an alternative +without these limitations. + +### Header lines + +At the beginning of each file, a header is printed using a similar format as +regular log entries. This header reports when the file was created, +which parameters were used to start the server, the server identifiers +if known, and other metadata about the running process. + +- This header appears to be logged at severity `INFO` (with an `I` prefix + at the start of the line) even though it does not really have a severity. +- The header is printed unconditionally even when a filter is configured to + omit entries at the `INFO` level. + +### Common log entry prefix + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker tags counter + +Reminder, the tags may be omitted; and the counter is only printed if the option +'show-counter' is specified. + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (omitted if zero for use by tests). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. | +| line | The line number where the entry originated. | +| marker | Redactability marker ` + redactableIndicator + ` (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. May be absent. | +| counter | The entry counter. Only included if 'show-counter' is enabled. | + +The redactability marker can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. + +If the marker ` + redactableIndicator + ` is present, the remainder of the log entry +contains delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `show-counter` | Whether to include the counter column in the line header. Without it, the format may be ambiguous due to the optionality of tags. | +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v1-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: none` + + +## Format `crdb-v1-tty` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: false` +- `colors: auto` + + +## Format `crdb-v1-tty-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: auto` + + +## Format `crdb-v2` + +This is the main file format used from CockroachDB v21.1. + +Each log entry is emitted using a common prefix, described below, +followed by the text of the log entry. + +### Entry format + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker [tags...] counter cont + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (zero when cannot be determined). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. Also see below. | +| line | The line number where the entry originated. | +| marker | Redactability marker "⋮" (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. See below. | +| counter | The optional entry counter (see below for details). | +| cont | Continuation mark for structured and multi-line entries. See below. | + +The `chan@` prefix before the file name indicates the logging channel, +and is omitted if the channel is `DEV`. + +The file name may be prefixed by the string `(gostd) ` to indicate +that the log entry was produced inside the Go standard library, instead +of a CockroachDB component. Entry parsers must be configured to ignore this prefix +when present. + +`marker` can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. +If the marker "⋮" is present, the remainder of the log entry +contains delimiters (‹...›) +around fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +when log redaction is requested. + +The logging `tags` are enclosed between square brackets `[...]`, +and the syntax `[-]` is used when there are no logging tags +associated with the log entry. + +`counter` is numeric, and is incremented for every +log entry emitted to this sink. (There is thus one counter sequence per +sink.) For entries that do not have a counter value +associated (e.g., header entries in file sinks), the counter position +in the common prefix is empty: `tags` is then +followed by two ASCII space characters, instead of one space; the `counter`, +and another space. The presence of the two ASCII spaces indicates +reliably that no counter was present. + +`cont` is a format/continuation indicator: + +| Continuation indicator | ASCII | Description | +|------------------------|-------|--| +| space | 0x32 | Start of an unstructured entry. | +| equal sign, "=" | 0x3d | Start of a structured entry. | +| exclamation mark, "!" | 0x21 | Start of an embedded stack trace. | +| plus sign, "+" | 0x2b | Continuation of a multi-line entry. The payload contains a newline character at this position. | +| vertical bar | 0x7c | Continuation of a large entry. | + +### Examples + +Example single-line unstructured entry: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 started with engine type ‹2› +~~~ + +Example multi-line unstructured entry: + +~~~ +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 node startup completed: +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 +CockroachDB node starting at 2021-01-16 21:49 (took 0.0s) +~~~ + +Example structured entry: + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventType":"node_restart"} +~~~ + +Example long entries broken up into multiple lines: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.... +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 |aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +~~~ + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventTy... +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 |pe":"node_restart"} +~~~ + +### Backward-compatibility notes + +Entries in this format can be read by most `crdb-v1` log parsers, +in particular the one included in the DB console and +also the [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +facility. + +However, implementers of previous version parsers must +understand that the logging tags field is now always +included, and the lack of logging tags is included +by a tag string set to `[-]`. + +Likewise, the entry counter is now also always included, +and there is a special character after `counter` +to indicate whether the remainder of the line is a +structured entry, or a continuation of a previous entry. + +Finally, in the previous format, structured entries +were prefixed with the string `Structured entry: `. In +the new format, they are prefixed by the `=` continuation +indicator. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v2-tty` + +This format name is an alias for 'crdb-v2' with +the following format option defaults: + +- `colors: auto` + + +## Format `json` + +This format emits log entries as a JSON payload. + +The JSON object is guaranteed to not contain unescaped newlines +or other special characters, and the entry as a whole is followed +by a newline character. This makes the format suitable for +processing over a stream unambiguously. + +Each entry contains at least the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `tag` | `tag` | (Only if the option `fluent-tag: true` is given.) A Fluent tag for the event, formed by the process name and the logging channel. | +| `d` | `datetime` | The pretty-printed date/time of the event timestamp, if enabled via options. | +| `f` | `file` | The name of the source file where the event was emitted. | +| `g` | `goroutine` | The identifier of the goroutine where the event was emitted. | +| `l` | `line` | The line number where the event was emitted in the source. | +| `r` | `redactable` | Whether the payload is redactable (see below for details). | +| `t` | `timestamp` | The timestamp at which the event was emitted on the logging channel. | +| `v` | `version` | The binary version with which the event was generated. | + + +After a couple of *header* entries written at the beginning of each log sink, +all subsequent log entries also contain the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `C` | `channel` | The name of the logging channel where the event was sent. | +| `sev` | `severity` | The severity of the event. | +| `c` | `channel_numeric` | The numeric identifier for the logging channel where the event was sent. | +| `n` | `entry_counter` | The entry number on this logging sink, relative to the last process restart. | +| `s` | `severity_numeric` | The numeric value of the severity of the event. | + + +Additionally, the following fields are conditionally present: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `N` | `node_id` | The node ID where the event was generated, once known. Only reported for single-tenant or KV servers. | +| `x` | `cluster_id` | The cluster ID where the event was generated, once known. Only reported for single-tenant of KV servers. | +| `q` | `instance_id` | The SQL instance ID where the event was generated, once known. | +| `T` | `tenant_id` | The SQL tenant ID where the event was generated, once known. | +| `V` | `tenant_name` | The SQL virtual cluster where the event was generated, once known. | +| `tags` | `tags` | The logging context tags for the entry, if there were context tags. | +| `message` | `message` | For unstructured events, the flat text payload. | +| `event` | `event` | The logging event, if structured (see below for details). | +| `stacks` | `stacks` | Goroutine stacks, for fatal events. | + +When an entry is structured, the `event` field maps to a dictionary +whose structure is one of the documented structured events. See the [reference documentation](eventlog.html) +for structured events for a list of possible payloads. + +When the entry is marked as `redactable`, the `tags`, `message`, and/or `event` payloads +contain delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `datetime-format` | The format to use for the `datetime` field. The value can be one of `none`, `iso8601`/`rfc3339` (synonyms), or `rfc1123`. Default is `none`. | +| `datetime-timezone` | The timezone to use for the `datetime` field. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | +| `tag-style` | The tags to include in the envelope. The value can be `compact` (one letter tags) or `verbose` (long-form tags). Default is `verbose`. | +| `fluent-tag` | Whether to produce an additional field called `tag` for Fluent compatibility. Default is `false`. | + + + +## Format `json-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: false` +- `tag-style: compact` + + +## Format `json-fluent` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: verbose` + + +## Format `json-fluent-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: compact` + + diff --git a/src/current/_includes/cockroach-generated/release-25.1/logging.md b/src/current/_includes/cockroach-generated/release-25.1/logging.md new file mode 100644 index 00000000000..8b628dc2dd9 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.1/logging.md @@ -0,0 +1,179 @@ +## Logging levels (severities) + +### INFO + +The `INFO` severity is used for informational messages that do not +require action. + +### WARNING + +The `WARNING` severity is used for situations which may require special handling, +where normal operation is expected to resume automatically. + +### ERROR + +The `ERROR` severity is used for situations that require special handling, +where normal operation could not proceed as expected. +Other operations can continue mostly unaffected. + +### FATAL + +The `FATAL` severity is used for situations that require an immedate, hard +server shutdown. A report is also sent to telemetry if telemetry +is enabled. + + +## Logging channels + +### `DEV` + +The `DEV` channel is used during development to collect log +details useful for troubleshooting that fall outside the +scope of other channels. It is also the default logging +channel for events not associated with a channel. + +This channel is special in that there are no constraints as to +what may or may not be logged on it. Conversely, users in +production deployments are invited to not collect `DEV` logs in +centralized logging facilities, because they likely contain +sensitive operational data. +See [Configure logs](configure-logs.html#dev-channel). + +### `OPS` + +The `OPS` channel is used to report "point" operational events, +initiated by user operators or automation: + + - Operator or system actions on server processes: process starts, + stops, shutdowns, crashes (if they can be logged), + including each time: command-line parameters, current version being run + - Actions that impact the topology of a cluster: node additions, + removals, decommissions, etc. + - Job-related initiation or termination + - [Cluster setting](cluster-settings.html) changes + - [Zone configuration](configure-replication-zones.html) changes + +### `HEALTH` + +The `HEALTH` channel is used to report "background" operational +events, initiated by CockroachDB or reporting on automatic processes: + + - Current resource usage, including critical resource usage + - Node-node connection events, including connection errors and + gossip details + - Range and table leasing events + - Up- and down-replication, range unavailability + +### `STORAGE` + +The `STORAGE` channel is used to report low-level storage +layer events (RocksDB/Pebble). + +### `SESSIONS` + +The `SESSIONS` channel is used to report client network activity when enabled via +the `server.auth_log.sql_connections.enabled` and/or +`server.auth_log.sql_sessions.enabled` [cluster setting](cluster-settings.html): + + - Connections opened/closed + - Authentication events: logins, failed attempts + - Session and query cancellation + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_SCHEMA` + +The `SQL_SCHEMA` channel is used to report changes to the +SQL logical schema, excluding privilege and ownership changes +(which are reported separately on the `PRIVILEGES` channel) and +zone configuration changes (which go to the `OPS` channel). + +This includes: + + - Database/schema/table/sequence/view/type creation + - Adding/removing/changing table columns + - Changing sequence parameters + +`SQL_SCHEMA` events generally comprise changes to the schema that affect the +functional behavior of client apps using stored objects. + +### `USER_ADMIN` + +The `USER_ADMIN` channel is used to report changes +in users and roles, including: + + - Users added/dropped + - Changes to authentication credentials (e.g., passwords, validity, etc.) + - Role grants/revocations + - Role option grants/revocations + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `PRIVILEGES` + +The `PRIVILEGES` channel is used to report data +authorization changes, including: + + - Privilege grants/revocations on database, objects, etc. + - Object ownership changes + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SENSITIVE_ACCESS` + +The `SENSITIVE_ACCESS` channel is used to report SQL +data access to sensitive data: + + - Data access audit events (when table audit is enabled via + [ALTER TABLE ... EXPERIMENTAL_AUDIT](alter-table.html#experimental_audit)) + - Data access audit events (when role-based audit is enabled via + [`sql.log.user_audit` cluster setting](role-based-audit-logging.html#syntax-of-audit-settings)) + - SQL statements executed by users with the admin role + - Operations that write to system tables + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_EXEC` + +The `SQL_EXEC` channel is used to report SQL execution on +behalf of client connections: + + - Logical SQL statement executions (when enabled via the + `sql.log.all_statements.enabled` [cluster setting](cluster-settings.html)) + - uncaught Go panic errors during the execution of a SQL statement. + +### `SQL_PERF` + +The `SQL_PERF` channel is used to report SQL executions +that are marked as "out of the ordinary" +to facilitate performance investigations. +This includes the SQL "slow query log". + +Arguably, this channel overlaps with `SQL_EXEC`. +However, we keep both channels separate for backward compatibility +with versions prior to v21.1, where the corresponding events +were redirected to separate files. + +### `SQL_INTERNAL_PERF` + +The `SQL_INTERNAL_PERF` channel is like the `SQL_PERF` channel, but is aimed at +helping developers of CockroachDB itself. It exists as a separate +channel so as to not pollute the `SQL_PERF` logging output with +internal troubleshooting details. + +### `TELEMETRY` + +The `TELEMETRY` channel reports telemetry events. Telemetry events describe +feature usage within CockroachDB and anonymizes any application- +specific data. + +### `KV_DISTRIBUTION` + +The `KV_DISTRIBUTION` channel is used to report data distribution events, such as moving +replicas between stores in the cluster, or adding (removing) replicas to +ranges. + diff --git a/src/current/_includes/cockroach-generated/release-25.1/settings/settings.html b/src/current/_includes/cockroach-generated/release-25.1/settings/settings.html new file mode 100644 index 00000000000..f2c718ec58b --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.1/settings/settings.html @@ -0,0 +1,371 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingTypeDefaultDescriptionSupported Deployments
admission.disk_bandwidth_tokens.elastic.enabled
booleantruewhen true, and provisioned bandwidth for the disk corresponding to a store is configured, tokens for elastic work will be limited if disk bandwidth becomes a bottleneckDedicated/Self-Hosted
admission.epoch_lifo.enabled
booleanfalsewhen true, epoch-LIFO behavior is enabled when there is significant delay in admissionServerless/Dedicated/Self-Hosted
admission.epoch_lifo.epoch_closing_delta_duration
duration5msthe delta duration before closing an epoch, for epoch-LIFO admission control orderingServerless/Dedicated/Self-Hosted
admission.epoch_lifo.epoch_duration
duration100msthe duration of an epoch, for epoch-LIFO admission control orderingServerless/Dedicated/Self-Hosted
admission.epoch_lifo.queue_delay_threshold_to_switch_to_lifo
duration105msthe queue delay encountered by a (tenant,priority) for switching to epoch-LIFO orderingServerless/Dedicated/Self-Hosted
admission.kv.enabled
booleantruewhen true, work performed by the KV layer is subject to admission controlDedicated/Self-Hosted
admission.sql_kv_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a KV response is subject to admission controlServerless/Dedicated/Self-Hosted
admission.sql_sql_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a DistSQL response is subject to admission controlServerless/Dedicated/Self-Hosted
bulkio.backup.deprecated_full_backup_with_subdir.enabled
booleanfalsewhen true, a backup command with a user specified subdirectory will create a full backup at the subdirectory if no backup already exists at that subdirectoryServerless/Dedicated/Self-Hosted
bulkio.backup.file_size
byte size128 MiBtarget size for individual data files produced during BACKUPServerless/Dedicated/Self-Hosted
bulkio.backup.read_timeout
duration5m0samount of time after which a read attempt is considered timed out, which causes the backup to failServerless/Dedicated/Self-Hosted
bulkio.backup.read_with_priority_after
duration1m0samount of time since the read-as-of time above which a BACKUP should use priority when retrying readsServerless/Dedicated/Self-Hosted
physical_replication.consumer.minimum_flush_interval
(alias: bulkio.stream_ingestion.minimum_flush_interval)
duration5sthe minimum timestamp between flushes; flushes may still occur if internal buffers fill upDedicated/Self-Hosted
changefeed.aggregator.flush_jitter
float0.1jitter aggregator flushes as a fraction of min_checkpoint_frequency. This setting has no effect if min_checkpoint_frequency is set to 0.Serverless/Dedicated/Self-Hosted
changefeed.backfill.concurrent_scan_requests
integer0number of concurrent scan requests per node issued during a backfillServerless/Dedicated/Self-Hosted
changefeed.backfill.scan_request_size
integer524288the maximum number of bytes returned by each scan requestServerless/Dedicated/Self-Hosted
changefeed.batch_reduction_retry.enabled
(alias: changefeed.batch_reduction_retry_enabled)
booleanfalseif true, kafka changefeeds upon erroring on an oversized batch will attempt to resend the messages with progressively lower batch sizesServerless/Dedicated/Self-Hosted
changefeed.default_range_distribution_strategy
enumerationdefaultconfigures how work is distributed among nodes for a given changefeed. for the most balanced distribution, use `balanced_simple`. changing this setting will not override locality restrictions [default = 0, balanced_simple = 1]Serverless/Dedicated/Self-Hosted
changefeed.event_consumer_worker_queue_size
integer16if changefeed.event_consumer_workers is enabled, this setting sets the maxmimum number of events which a worker can bufferServerless/Dedicated/Self-Hosted
changefeed.event_consumer_workers
integer0the number of workers to use when processing events: <0 disables, 0 assigns a reasonable default, >0 assigns the setting value. for experimental/core changefeeds and changefeeds using parquet format, this is disabledServerless/Dedicated/Self-Hosted
changefeed.fast_gzip.enabled
booleantrueuse fast gzip implementationServerless/Dedicated/Self-Hosted
changefeed.span_checkpoint.lag_threshold
(alias: changefeed.frontier_highwater_lag_checkpoint_threshold)
duration10m0sthe amount of time a changefeed's lagging (slowest) spans must lag behind its leading (fastest) spans before a span-level checkpoint to save leading span progress is written; if 0, span-level checkpoints due to lagging spans is disabledServerless/Dedicated/Self-Hosted
changefeed.kafka_v2_error_details.enabled
booleanfalseif enabled, Kafka v2 sinks will include the message key, size, and MVCC timestamp in message too large errorsServerless/Dedicated/Self-Hosted
changefeed.memory.per_changefeed_limit
byte size512 MiBcontrols amount of data that can be buffered per changefeedServerless/Dedicated/Self-Hosted
changefeed.resolved_timestamp.min_update_interval
(alias: changefeed.min_highwater_advance)
duration0sminimum amount of time that must have elapsed since the last time a changefeed's resolved timestamp was updated before it is eligible to be updated again; default of 0 means no minimum interval is enforced but updating will still be limited by the average time it takes to checkpoint progressServerless/Dedicated/Self-Hosted
changefeed.node_throttle_config
stringspecifies node level throttling configuration for all changefeeedsServerless/Dedicated/Self-Hosted
changefeed.protect_timestamp.max_age
duration96h0m0sfail the changefeed if the protected timestamp age exceeds this threshold; 0 disables expirationServerless/Dedicated/Self-Hosted
changefeed.protect_timestamp_interval
duration10m0scontrols how often the changefeed forwards its protected timestamp to the resolved timestampServerless/Dedicated/Self-Hosted
changefeed.schema_feed.read_with_priority_after
duration1m0sretry with high priority if we were not able to read descriptors for too long; 0 disablesServerless/Dedicated/Self-Hosted
changefeed.sink_io_workers
integer0the number of workers used by changefeeds when sending requests to the sink (currently the batching versions of webhook, pubsub, and kafka sinks that are enabled by changefeed.new_<sink type>_sink_enabled only): <0 disables, 0 assigns a reasonable default, >0 assigns the setting valueServerless/Dedicated/Self-Hosted
cloudstorage.azure.concurrent_upload_buffers
integer1controls the number of concurrent buffers that will be used by the Azure client when uploading chunks.Each buffer can buffer up to cloudstorage.write_chunk.size of memory during an uploadServerless/Dedicated/Self-Hosted
cloudstorage.azure.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.azure.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.azure.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.azure.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.gs.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.gs.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.gs.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.gs.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.http.custom_ca
stringcustom root CA (appended to system's default CAs) for verifying certificates when interacting with HTTPS storageServerless/Dedicated/Self-Hosted
cloudstorage.http.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.http.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.http.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.http.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nodelocal.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nodelocal.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nodelocal.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nodelocal.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nullsink.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nullsink.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nullsink.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nullsink.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.s3.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.s3.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.s3.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.s3.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.timeout
duration10m0sthe timeout for import/export storage operationsServerless/Dedicated/Self-Hosted
cloudstorage.userfile.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.userfile.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.userfile.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.userfile.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cluster.auto_upgrade.enabled
booleantruedisable automatic cluster version upgrade until resetServerless/Dedicated/Self-Hosted
cluster.organization
stringorganization nameDedicated/Self-hosted (read-write); Serverless (read-only)
cluster.preserve_downgrade_option
stringdisable (automatic or manual) cluster version upgrade from the specified version until resetServerless/Dedicated/Self-Hosted
debug.zip.redact_addresses.enabled
booleanfalseenables the redaction of hostnames and ip addresses in debug zipServerless/Dedicated/Self-Hosted
diagnostics.active_query_dumps.enabled
booleantrueexperimental: enable dumping of anonymized active queries to disk when node is under memory pressureDedicated/Self-hosted (read-write); Serverless (read-only)
diagnostics.forced_sql_stat_reset.interval
duration2h0m0sinterval after which the reported SQL Stats are reset even if not collected by telemetry reporter. It has a max value of 24H.Serverless/Dedicated/Self-Hosted
diagnostics.memory_monitoring_dumps.enabled
booleantrueenable dumping of memory monitoring state at the same time as heap profiles are takenDedicated/Self-hosted (read-write); Serverless (read-only)
diagnostics.reporting.enabled
booleantrueenable reporting diagnostic metrics to cockroach labs, but is ignored for Trial or Free licensesServerless/Dedicated/Self-Hosted
diagnostics.reporting.interval
duration1h0m0sinterval at which diagnostics data should be reportedServerless/Dedicated/Self-Hosted
enterprise.license
stringthe encoded cluster licenseDedicated/Self-hosted (read-write); Serverless (read-only)
external.graphite.endpoint
stringif nonempty, push server metrics to the Graphite or Carbon server at the specified host:portServerless/Dedicated/Self-Hosted
external.graphite.interval
duration10sthe interval at which metrics are pushed to Graphite (if enabled)Serverless/Dedicated/Self-Hosted
feature.backup.enabled
booleantrueset to true to enable backups, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.changefeed.enabled
booleantrueset to true to enable changefeeds, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.export.enabled
booleantrueset to true to enable exports, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.import.enabled
booleantrueset to true to enable imports, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.restore.enabled
booleantrueset to true to enable restore, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.schema_change.enabled
booleantrueset to true to enable schema changes, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.stats.enabled
booleantrueset to true to enable CREATE STATISTICS/ANALYZE, false to disable; default is trueServerless/Dedicated/Self-Hosted
jobs.retention_time
duration336h0m0sthe amount of time for which records for completed jobs are retainedServerless/Dedicated/Self-Hosted
kv.allocator.lease_rebalance_threshold
float0.05minimum fraction away from the mean a store's lease count can be before it is considered for lease-transfersDedicated/Self-Hosted
kv.allocator.load_based_lease_rebalancing.enabled
booleantrueset to enable rebalancing of range leases based on load and latencyDedicated/Self-Hosted
kv.allocator.load_based_rebalancing
enumerationleases and replicaswhether to rebalance based on the distribution of load across stores [off = 0, leases = 1, leases and replicas = 2]Dedicated/Self-Hosted
kv.allocator.load_based_rebalancing.objective
enumerationcpuwhat objective does the cluster use to rebalance; if set to `qps` the cluster will attempt to balance qps among stores, if set to `cpu` the cluster will attempt to balance cpu usage among stores [qps = 0, cpu = 1]Dedicated/Self-Hosted
kv.allocator.load_based_rebalancing_interval
duration1m0sthe rough interval at which each store will check for load-based lease / replica rebalancing opportunitiesDedicated/Self-Hosted
kv.allocator.qps_rebalance_threshold
float0.1minimum fraction away from the mean a store's QPS (such as queries per second) can be before it is considered overfull or underfullDedicated/Self-Hosted
kv.allocator.range_rebalance_threshold
float0.05minimum fraction away from the mean a store's range count can be before it is considered overfull or underfullDedicated/Self-Hosted
kv.allocator.store_cpu_rebalance_threshold
float0.1minimum fraction away from the mean a store's cpu usage can be before it is considered overfull or underfullDedicated/Self-Hosted
kv.bulk_io_write.max_rate
byte size1.0 TiBthe rate limit (bytes/sec) to use for writes to disk on behalf of bulk io opsDedicated/Self-Hosted
kv.bulk_io_write.min_capacity_remaining_fraction
float0.05remaining store capacity fraction below which bulk ingestion requests are rejectedDedicated/Self-Hosted
kv.bulk_sst.max_allowed_overage
byte size64 MiBif positive, allowed size in excess of target size for SSTs from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryDedicated/Self-Hosted
kv.bulk_sst.target_size
byte size16 MiBtarget size for SSTs emitted from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryDedicated/Self-hosted (read-write); Serverless (read-only)
kv.closed_timestamp.follower_reads.enabled
(alias: kv.closed_timestamp.follower_reads_enabled)
booleantrueallow (all) replicas to serve consistent historical reads based on closed timestamp informationDedicated/Self-hosted (read-write); Serverless (read-only)
kv.closed_timestamp.lead_for_global_reads_override
duration0sif nonzero, overrides the lead time that global_read ranges use to publish closed timestampsDedicated/Self-hosted (read-write); Serverless (read-only)
kv.closed_timestamp.side_transport_interval
duration200msthe interval at which the closed timestamp side-transport attempts to advance each range's closed timestamp; set to 0 to disable the side-transportDedicated/Self-hosted (read-write); Serverless (read-only)
kv.closed_timestamp.target_duration
duration3sif nonzero, attempt to provide closed timestamp notifications for timestamps trailing cluster time by approximately this durationDedicated/Self-hosted (read-write); Serverless (read-only)
kv.dist_sender.circuit_breaker.cancellation.enabled
booleantruewhen enabled, in-flight requests will be cancelled when the circuit breaker tripsServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.cancellation.write_grace_period
duration10show long after the circuit breaker trips to cancel write requests (these can't retry internally, so should be long enough to allow quorum/lease recovery)Serverless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.probe.interval
duration3sinterval between replica probesServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.probe.threshold
duration3sduration of errors or stalls after which a replica will be probedServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.probe.timeout
duration3stimeout for replica probesServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breakers.mode
enumerationliveness range onlyset of ranges to trip circuit breakers for failing or stalled replicas [no ranges = 0, liveness range only = 1, all ranges = 2]Serverless/Dedicated/Self-Hosted
kv.lease_transfer_read_summary.global_budget
byte size0 Bcontrols the maximum number of bytes that will be used to summarize the global segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Dedicated/Self-Hosted
kv.lease_transfer_read_summary.local_budget
byte size4.0 MiBcontrols the maximum number of bytes that will be used to summarize the local segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Dedicated/Self-Hosted
kv.log_range_and_node_events.enabled
booleantrueset to true to transactionally log range events (e.g., split, merge, add/remove voter/non-voter) into system.rangelogand node join and restart events into system.eventologDedicated/Self-Hosted
kv.protectedts.reconciliation.interval
duration5m0sthe frequency for reconciling jobs with protected timestamp recordsDedicated/Self-hosted (read-write); Serverless (read-only)
kv.raft.leader_fortification.fraction_enabled
float0controls the fraction of ranges for which the raft leader fortification protocol is enabled. Leader fortification is needed for a range to use a Leader lease. Set to 0.0 to disable leader fortification and, by extension, Leader leases. Set to 1.0 to enable leader fortification for all ranges and, by extension, use Leader leases for all ranges which do not require expiration-based leases. Set to a value between 0.0 and 1.0 to gradually roll out Leader leases across the ranges in a cluster.Dedicated/Self-Hosted
kv.range.range_size_hard_cap
byte size8.0 GiBhard cap on the maximum size a range is allowed to grow to withoutsplitting before writes to the range are blocked. Takes precedence over all other configurationsDedicated/Self-Hosted
kv.range_split.by_load.enabled
(alias: kv.range_split.by_load_enabled)
booleantrueallow automatic splits of ranges based on where load is concentratedDedicated/Self-Hosted
kv.range_split.load_cpu_threshold
duration500msthe CPU use per second over which, the range becomes a candidate for load based splittingDedicated/Self-Hosted
kv.range_split.load_qps_threshold
integer2500the QPS over which, the range becomes a candidate for load based splittingDedicated/Self-Hosted
kv.rangefeed.client.stream_startup_rate
integer100controls the rate per second the client will initiate new rangefeed stream for a single range; 0 implies unlimitedServerless/Dedicated/Self-Hosted
kv.rangefeed.closed_timestamp_refresh_interval
duration3sthe interval at which closed-timestamp updatesare delivered to rangefeeds; set to 0 to use kv.closed_timestamp.side_transport_intervalDedicated/Self-hosted (read-write); Serverless (read-only)
kv.rangefeed.enabled
booleanfalseif set, rangefeed registration is enabledDedicated/Self-hosted (read-write); Serverless (read-only)
kv.replica_circuit_breaker.slow_replication_threshold
duration1m0sduration after which slow proposals trip the per-Replica circuit breaker (zero duration disables breakers)Dedicated/Self-Hosted
kv.replica_stats.addsst_request_size_factor
integer50000the divisor that is applied to addsstable request sizes, then recorded in a leaseholders QPS; 0 means all requests are treated as cost 1Dedicated/Self-Hosted
kv.replication_reports.interval
duration1m0sthe frequency for generating the replication_constraint_stats, replication_stats_report and replication_critical_localities reports (set to 0 to disable)Dedicated/Self-Hosted
kv.snapshot_rebalance.max_rate
byte size32 MiBthe rate limit (bytes/sec) to use for rebalance and upreplication snapshotsDedicated/Self-Hosted
kv.snapshot_receiver.excise.enabled
booleantrueset to false to disable excises in place of range deletions for KV snapshotsDedicated/Self-Hosted
kv.transaction.max_intents_and_locks
integer0maximum count of inserts or durable locks for a single transactions, 0 to disableServerless/Dedicated/Self-Hosted
kv.transaction.max_intents_bytes
integer4194304maximum number of bytes used to track locks in transactionsServerless/Dedicated/Self-Hosted
kv.transaction.max_refresh_spans_bytes
integer4194304maximum number of bytes used to track refresh spans in serializable transactionsServerless/Dedicated/Self-Hosted
kv.transaction.randomized_anchor_key.enabled
booleanfalsedictates whether a transactions anchor key is randomized or notServerless/Dedicated/Self-Hosted
kv.transaction.reject_over_max_intents_budget.enabled
booleanfalseif set, transactions that exceed their lock tracking budget (kv.transaction.max_intents_bytes) are rejected instead of having their lock spans imprecisely compressedServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.locking_reads.enabled
booleantrueif enabled, transactional locking reads are pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.ranged_writes.enabled
booleantrueif enabled, transactional ranged writes are pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.enabled
(alias: kv.transaction.write_pipelining_enabled)
booleantrueif enabled, transactional writes are pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.max_batch_size
(alias: kv.transaction.write_pipelining_max_batch_size)
integer128if non-zero, defines that maximum size batch that will be pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kvadmission.store.provisioned_bandwidth
byte size0 Bif set to a non-zero value, this is used as the provisioned bandwidth (in bytes/s), for each store. It can be overridden on a per-store basis using the --store flag. Note that setting the provisioned bandwidth to a positive value may enable disk bandwidth based admission control, since admission.disk_bandwidth_tokens.elastic.enabled defaults to trueDedicated/Self-Hosted
kvadmission.store.snapshot_ingest_bandwidth_control.enabled
booleantrueif set to true, snapshot ingests will be subject to disk write control in ACDedicated/Self-Hosted
obs.tablemetadata.automatic_updates.enabled
booleanfalseenables automatic updates of the table metadata cache system.table_metadataServerless/Dedicated/Self-Hosted
obs.tablemetadata.data_valid_duration
duration20m0sthe duration for which the data in system.table_metadata is considered validServerless/Dedicated/Self-Hosted
schedules.backup.gc_protection.enabled
booleantrueenable chaining of GC protection across backups run as part of a scheduleServerless/Dedicated/Self-Hosted
security.client_cert.subject_required.enabled
booleanfalsemandates a requirement for subject role to be set for db userDedicated/Self-hosted (read-write); Serverless (read-only)
security.ocsp.mode
enumerationoffuse OCSP to check whether TLS certificates are revoked. If the OCSP server is unreachable, in strict mode all certificates will be rejected and in lax mode all certificates will be accepted. [off = 0, lax = 1, strict = 2]Serverless/Dedicated/Self-Hosted
security.ocsp.timeout
duration3stimeout before considering the OCSP server unreachableServerless/Dedicated/Self-Hosted
server.auth_log.sql_connections.enabled
booleanfalseif set, log SQL client connect and disconnect events to the SESSIONS log channel (note: may hinder performance on loaded nodes)Serverless/Dedicated/Self-Hosted
server.auth_log.sql_sessions.enabled
booleanfalseif set, log verbose SQL session authentication events to the SESSIONS log channel (note: may hinder performance on loaded nodes). Session start and end events are always logged regardless of this setting; disable the SESSIONS log channel to suppress them.Serverless/Dedicated/Self-Hosted
server.authentication_cache.enabled
booleantrueenables a cache used during authentication to avoid lookups to system tables when retrieving per-user authentication-related informationServerless/Dedicated/Self-Hosted
server.child_metrics.enabled
booleanfalseenables the exporting of child metrics, additional prometheus time series with extra labelsServerless/Dedicated/Self-Hosted
server.child_metrics.include_aggregate.enabled
booleantrueinclude the reporting of the aggregate time series when child metrics are enabled. This cluster setting has no effect if child metrics are disabled.Serverless/Dedicated/Self-Hosted
server.client_cert_expiration_cache.capacity
integer1000the maximum number of client cert expirations storedServerless/Dedicated/Self-Hosted
server.clock.forward_jump_check.enabled
(alias: server.clock.forward_jump_check_enabled)
booleanfalseif enabled, forward clock jumps > max_offset/2 will cause a panicServerless/Dedicated/Self-Hosted
server.clock.persist_upper_bound_interval
duration0sthe interval between persisting the wall time upper bound of the clock. The clock does not generate a wall time greater than the persisted timestamp and will panic if it sees a wall time greater than this value. When cockroach starts, it waits for the wall time to catch-up till this persisted timestamp. This guarantees monotonic wall time across server restarts. Not setting this or setting a value of 0 disables this feature.Serverless/Dedicated/Self-Hosted
server.consistency_check.max_rate
byte size8.0 MiBthe rate limit (bytes/sec) to use for consistency checks; used in conjunction with server.consistency_check.interval to control the frequency of consistency checks. Note that setting this too high can negatively impact performance.Dedicated/Self-Hosted
server.eventlog.enabled
booleantrueif set, logged notable events are also stored in the table system.eventlogServerless/Dedicated/Self-Hosted
server.eventlog.ttl
duration2160h0m0sif nonzero, entries in system.eventlog older than this duration are periodically purgedServerless/Dedicated/Self-Hosted
server.host_based_authentication.configuration
stringhost-based authentication configuration to use during connection authenticationServerless/Dedicated/Self-Hosted
server.hot_ranges_request.node.timeout
duration5m0sthe duration allowed for a single node to return hot range data before the request is cancelled; if set to 0, there is no timeoutServerless/Dedicated/Self-Hosted
server.hsts.enabled
booleanfalseif true, HSTS headers will be sent along with all HTTP requests. The headers will contain a max-age setting of one year. Browsers honoring the header will always use HTTPS to access the DB Console. Ensure that TLS is correctly configured prior to enabling.Serverless/Dedicated/Self-Hosted
server.http.base_path
string/path to redirect the user to upon succcessful loginServerless/Dedicated/Self-Hosted
server.identity_map.configuration
stringsystem-identity to database-username mappingsServerless/Dedicated/Self-Hosted
server.jwt_authentication.audience
stringsets accepted audience values for JWT logins over the SQL interfaceServerless/Dedicated/Self-Hosted
server.jwt_authentication.claim
stringsets the JWT claim that is parsed to get the usernameServerless/Dedicated/Self-Hosted
server.jwt_authentication.client.timeout
duration15ssets the client timeout for external calls made during JWT authentication (e.g. fetching JWKS, etc.)Serverless/Dedicated/Self-Hosted
server.jwt_authentication.enabled
booleanfalseenables or disables JWT login for the SQL interfaceServerless/Dedicated/Self-Hosted
server.jwt_authentication.issuers.configuration
(alias: server.jwt_authentication.issuers)
stringsets accepted issuer values for JWT logins over the SQL interface which can be a single issuer URL string or a JSON string containing an array of issuer URLs or a JSON object containing map of issuer URLS to JWKS URIsServerless/Dedicated/Self-Hosted
server.jwt_authentication.issuers.custom_ca
stringsets the PEM encoded custom root CA for verifying certificates while fetching JWKSServerless/Dedicated/Self-Hosted
server.jwt_authentication.jwks
string{"keys":[]}sets the public key set for JWT logins over the SQL interface (JWKS format)Serverless/Dedicated/Self-Hosted
server.jwt_authentication.jwks_auto_fetch.enabled
booleanfalseenables or disables automatic fetching of JWKS from the issuer's well-known endpoint or JWKS URI set in JWTAuthIssuersConfig. If this is enabled, the server.jwt_authentication.jwks will be ignored.Serverless/Dedicated/Self-Hosted
server.ldap_authentication.client.tls_certificate
stringsets the client certificate PEM for establishing mTLS connection with LDAP serverServerless/Dedicated/Self-Hosted
server.ldap_authentication.client.tls_key
stringsets the client key PEM for establishing mTLS connection with LDAP serverServerless/Dedicated/Self-Hosted
server.ldap_authentication.domain.custom_ca
stringsets the PEM encoded custom root CA for verifying domain certificates when establishing connection with LDAP serverServerless/Dedicated/Self-Hosted
server.log_gc.max_deletions_per_cycle
integer1000the maximum number of entries to delete on each purge of log-like system tablesServerless/Dedicated/Self-Hosted
server.log_gc.period
duration1h0m0sthe period at which log-like system tables are checked for old entriesServerless/Dedicated/Self-Hosted
server.max_connections_per_gateway
integer-1the maximum number of SQL connections per gateway allowed at a given time (note: this will only limit future connection attempts and will not affect already established connections). Negative values result in unlimited number of connections. Superusers are not affected by this limit.Serverless/Dedicated/Self-Hosted
server.max_open_transactions_per_gateway
integer-1the maximum number of open SQL transactions per gateway allowed at a given time. Negative values result in unlimited number of connections. Superusers are not affected by this limit.Serverless/Dedicated/Self-Hosted
server.oidc_authentication.autologin.enabled
(alias: server.oidc_authentication.autologin)
booleanfalseif true, logged-out visitors to the DB Console will be automatically redirected to the OIDC login endpointServerless/Dedicated/Self-Hosted
server.oidc_authentication.button_text
stringLog in with your OIDC providertext to show on button on DB Console login page to login with your OIDC provider (only shown if OIDC is enabled)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.claim_json_key
stringsets JSON key of principal to extract from payload after OIDC authentication completes (usually email or sid)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.client.timeout
duration15ssets the client timeout for external calls made during OIDC authentication (e.g. authorization code flow, etc.)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.client_id
stringsets OIDC client idServerless/Dedicated/Self-Hosted
server.oidc_authentication.client_secret
stringsets OIDC client secretServerless/Dedicated/Self-Hosted
server.oidc_authentication.enabled
booleanfalseenables or disabled OIDC login for the DB ConsoleServerless/Dedicated/Self-Hosted
server.oidc_authentication.principal_regex
string(.+)regular expression to apply to extracted principal (see claim_json_key setting) to translate to SQL user (golang regex format, must include 1 grouping to extract)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.provider_url
stringsets OIDC provider URL ({provider_url}/.well-known/openid-configuration must resolve)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.redirect_url
stringhttps://localhost:8080/oidc/v1/callbacksets OIDC redirect URL via a URL string or a JSON string containing a required `redirect_urls` key with an object that maps from region keys to URL strings (URLs should point to your load balancer and must route to the path /oidc/v1/callback)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.scopes
stringopenidsets OIDC scopes to include with authentication request (space delimited list of strings, required to start with `openid`)Serverless/Dedicated/Self-Hosted
server.rangelog.ttl
duration720h0m0sif nonzero, entries in system.rangelog older than this duration are periodically purgedDedicated/Self-Hosted
server.redact_sensitive_settings.enabled
booleanfalseenables or disables the redaction of sensitive settings in the output of SHOW CLUSTER SETTINGS and SHOW ALL CLUSTER SETTINGS for users without the MODIFYCLUSTERSETTING privilegeServerless/Dedicated/Self-Hosted
server.shutdown.connections.timeout
(alias: server.shutdown.connection_wait)
duration0sthe maximum amount of time a server waits for all SQL connections to be closed before proceeding with a drain. (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Serverless/Dedicated/Self-Hosted
server.shutdown.initial_wait
(alias: server.shutdown.drain_wait)
duration0sthe amount of time a server waits in an unready state before proceeding with a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting. --drain-wait is to specify the duration of the whole draining process, while server.shutdown.initial_wait is to set the wait time for health probes to notice that the node is not ready.)Serverless/Dedicated/Self-Hosted
server.shutdown.lease_transfer_iteration.timeout
(alias: server.shutdown.lease_transfer_wait)
duration5sthe timeout for a single iteration of the range lease transfer phase of draining (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Dedicated/Self-Hosted
server.shutdown.transactions.timeout
(alias: server.shutdown.query_wait)
duration10sthe timeout for waiting for active transactions to finish during a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Serverless/Dedicated/Self-Hosted
server.sql_tcp_keep_alive.count
integer3maximum number of probes that will be sent out before a connection is dropped because it's unresponsive (Linux and Darwin only)Serverless/Dedicated/Self-Hosted
server.sql_tcp_keep_alive.interval
duration10stime between keep alive probes and idle time before probes are sent outServerless/Dedicated/Self-Hosted
server.time_until_store_dead
duration5m0sthe time after which if there is no new gossiped information about a store, it is considered deadServerless/Dedicated/Self-Hosted
server.user_login.cert_password_method.auto_scram_promotion.enabled
booleantruewhether to automatically promote cert-password authentication to use SCRAMServerless/Dedicated/Self-Hosted
server.user_login.downgrade_scram_stored_passwords_to_bcrypt.enabled
booleantrueif server.user_login.password_encryption=crdb-bcrypt, this controls whether to automatically re-encode stored passwords using scram-sha-256 to crdb-bcryptServerless/Dedicated/Self-Hosted
server.user_login.min_password_length
integer1the minimum length accepted for passwords set in cleartext via SQL. Note that a value lower than 1 is ignored: passwords cannot be empty in any case. This setting only applies when adding new users or altering an existing user's password; it will not affect existing logins.Serverless/Dedicated/Self-Hosted
server.user_login.password_encryption
enumerationscram-sha-256which hash method to use to encode cleartext passwords passed via ALTER/CREATE USER/ROLE WITH PASSWORD [crdb-bcrypt = 2, scram-sha-256 = 3]Serverless/Dedicated/Self-Hosted
server.user_login.password_hashes.default_cost.crdb_bcrypt
integer10the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method crdb-bcrypt (allowed range: 4-31)Serverless/Dedicated/Self-Hosted
server.user_login.password_hashes.default_cost.scram_sha_256
integer10610the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method scram-sha-256 (allowed range: 4096-240000000000)Serverless/Dedicated/Self-Hosted
server.user_login.rehash_scram_stored_passwords_on_cost_change.enabled
booleantrueif server.user_login.password_hashes.default_cost.scram_sha_256 differs from, the cost in a stored hash, this controls whether to automatically re-encode stored passwords using scram-sha-256 with the new default costServerless/Dedicated/Self-Hosted
server.user_login.timeout
duration10stimeout after which client authentication times out if some system range is unavailable (0 = no timeout)Serverless/Dedicated/Self-Hosted
server.user_login.upgrade_bcrypt_stored_passwords_to_scram.enabled
booleantrueif server.user_login.password_encryption=scram-sha-256, this controls whether to automatically re-encode stored passwords using crdb-bcrypt to scram-sha-256Serverless/Dedicated/Self-Hosted
server.web_session.purge.ttl
duration1h0m0sif nonzero, entries in system.web_sessions older than this duration are periodically purgedServerless/Dedicated/Self-Hosted
server.web_session.timeout
(alias: server.web_session_timeout)
duration168h0m0sthe duration that a newly created web session will be validServerless/Dedicated/Self-Hosted
spanconfig.bounds.enabled
booleantruedictates whether span config bounds are consulted when serving span configs for secondary tenantsDedicated/Self-Hosted
spanconfig.range_coalescing.system.enabled
(alias: spanconfig.storage_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs, for the ranges specific to the system tenantDedicated/Self-Hosted
spanconfig.range_coalescing.application.enabled
(alias: spanconfig.tenant_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs across all secondary tenant keyspacesDedicated/Self-Hosted
sql.auth.change_own_password.enabled
booleanfalsecontrols whether a user is allowed to change their own password, even if they have no other privilegesServerless/Dedicated/Self-Hosted
sql.auth.grant_option_for_owner.enabled
booleantruedetermines whether the GRANT OPTION for privileges is implicitly given to the owner of an objectServerless/Dedicated/Self-Hosted
sql.auth.grant_option_inheritance.enabled
booleantruedetermines whether the GRANT OPTION for privileges is inherited through role membershipServerless/Dedicated/Self-Hosted
sql.auth.public_schema_create_privilege.enabled
booleantruedetermines whether to grant all users the CREATE privileges on the public schema when it is createdServerless/Dedicated/Self-Hosted
sql.closed_session_cache.capacity
integer1000the maximum number of sessions in the cacheServerless/Dedicated/Self-Hosted
sql.closed_session_cache.time_to_live
integer3600the maximum time to live, in secondsServerless/Dedicated/Self-Hosted
sql.contention.event_store.capacity
byte size64 MiBthe in-memory storage capacity per-node of contention event storeServerless/Dedicated/Self-Hosted
sql.contention.event_store.duration_threshold
duration0sminimum contention duration to cause the contention events to be collected into crdb_internal.transaction_contention_eventsServerless/Dedicated/Self-Hosted
sql.contention.record_serialization_conflicts.enabled
booleantrueenables recording 40001 errors with conflicting txn meta as SERIALIZATION_CONFLICTcontention events into crdb_internal.transaction_contention_eventsServerless/Dedicated/Self-Hosted
sql.contention.txn_id_cache.max_size
byte size64 MiBthe maximum byte size TxnID cache will use (set to 0 to disable)Serverless/Dedicated/Self-Hosted
sql.cross_db_fks.enabled
booleanfalseif true, creating foreign key references across databases is allowedServerless/Dedicated/Self-Hosted
sql.cross_db_sequence_owners.enabled
booleanfalseif true, creating sequences owned by tables from other databases is allowedServerless/Dedicated/Self-Hosted
sql.cross_db_sequence_references.enabled
booleanfalseif true, sequences referenced by tables from other databases are allowedServerless/Dedicated/Self-Hosted
sql.cross_db_views.enabled
booleanfalseif true, creating views that refer to other databases is allowedServerless/Dedicated/Self-Hosted
sql.defaults.cost_scans_with_default_col_size.enabled
booleanfalsesetting to true uses the same size for all columns to compute scan cost
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.datestyle
enumerationiso, mdydefault value for DateStyle session setting [iso, mdy = 0, iso, dmy = 1, iso, ymd = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.default_hash_sharded_index_bucket_count
integer16used as bucket count if bucket count is not specified in hash sharded index definition
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.default_int_size
integer8the size, in bytes, of an INT type
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.disallow_full_table_scans.enabled
booleanfalsesetting to true rejects queries that have planned a full table scan; set large_full_scan_rows > 0 to allow small full table scans estimated to read fewer than large_full_scan_rows
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.distsql
enumerationautodefault distributed SQL execution mode [off = 0, auto = 1, on = 2, always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_alter_column_type.enabled
booleanfalsedefault value for experimental_alter_column_type session setting; enables the use of ALTER COLUMN TYPE for general conversions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_distsql_planning
enumerationoffdefault experimental_distsql_planning mode; enables experimental opt-driven DistSQL planning [off = 0, on = 1]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_enable_unique_without_index_constraints.enabled
booleanfalsedefault value for experimental_enable_unique_without_index_constraints session setting;disables unique without index constraints by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_implicit_column_partitioning.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for the use of implicit column partitioning
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_temporary_tables.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for use of temporary tables by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.foreign_key_cascades_limit
integer10000default value for foreign_key_cascades_limit session setting; limits the number of cascading operations that run as part of a single query
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.idle_in_session_timeout
duration0sdefault value for the idle_in_session_timeout; default value for the idle_in_session_timeout session setting; controls the duration a session is permitted to idle before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.idle_in_transaction_session_timeout
duration0sdefault value for the idle_in_transaction_session_timeout; controls the duration a session is permitted to idle in a transaction before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.implicit_select_for_update.enabled
booleantruedefault value for enable_implicit_select_for_update session setting; enables FOR UPDATE locking during the row-fetch phase of mutation statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.insert_fast_path.enabled
booleantruedefault value for enable_insert_fast_path session setting; enables a specialized insert path
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.intervalstyle
enumerationpostgresdefault value for IntervalStyle session setting [postgres = 0, iso_8601 = 1, sql_standard = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.large_full_scan_rows
float0default value for large_full_scan_rows session variable which determines the table size at which full scans are considered large and disallowed when disallow_full_table_scans is set to true; set to 0 to reject all full table or full index scans when disallow_full_table_scans is true
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.locality_optimized_partitioned_index_scan.enabled
booleantruedefault value for locality_optimized_partitioned_index_scan session setting; enables searching for rows in the current region before searching remote regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.lock_timeout
duration0sdefault value for the lock_timeout; default value for the lock_timeout session setting; controls the duration a query is permitted to wait while attempting to acquire a lock on a key or while blocking on an existing lock in order to perform a non-locking read on a key; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.on_update_rehome_row.enabled
booleantruedefault value for on_update_rehome_row; enables ON UPDATE rehome_row() expressions to trigger on updates
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.optimizer_use_histograms.enabled
booleantruedefault value for optimizer_use_histograms session setting; enables usage of histograms in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.optimizer_use_multicol_stats.enabled
booleantruedefault value for optimizer_use_multicol_stats session setting; enables usage of multi-column stats in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.override_alter_primary_region_in_super_region.enabled
booleanfalsedefault value for override_alter_primary_region_in_super_region; allows for altering the primary region even if the primary region is a member of a super region
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.override_multi_region_zone_config.enabled
booleanfalsedefault value for override_multi_region_zone_config; allows for overriding the zone configs of a multi-region table or database
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.prefer_lookup_joins_for_fks.enabled
booleanfalsedefault value for prefer_lookup_joins_for_fks session setting; causes foreign key operations to use lookup joins when possible
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.primary_region
stringif not empty, all databases created without a PRIMARY REGION will implicitly have the given PRIMARY REGION
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.reorder_joins_limit
integer8default number of joins to reorder
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.require_explicit_primary_keys.enabled
booleanfalsedefault value for requiring explicit primary keys in CREATE TABLE statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.results_buffer.size
byte size512 KiBdefault size of the buffer that accumulates results for a statement or a batch of statements before they are sent to the client. This can be overridden on an individual connection with the 'results_buffer_size' parameter. Note that auto-retries generally only happen while no results have been delivered to the client, so reducing this size can increase the number of retriable errors a client receives. On the other hand, increasing the buffer size can increase the delay until the client receives the first result row. Updating the setting only affects new connections. Setting to 0 disables any buffering.
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.serial_normalization
enumerationrowiddefault handling of SERIAL in table definitions [rowid = 0, virtual_sequence = 1, sql_sequence = 2, sql_sequence_cached = 3, unordered_rowid = 4, sql_sequence_cached_node = 5]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.statement_timeout
duration0sdefault value for the statement_timeout; default value for the statement_timeout session setting; controls the duration a query is permitted to run before it is canceled; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.stub_catalog_tables.enabled
booleantruedefault value for stub_catalog_tables session setting
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.super_regions.enabled
booleanfalsedefault value for enable_super_regions; allows for the usage of super regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_read_err
integer0the limit for the number of rows read by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_read_log
integer0the threshold for the number of rows read by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_written_err
integer0the limit for the number of rows written by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_written_log
integer0the threshold for the number of rows written by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.use_declarative_schema_changer
enumerationondefault value for use_declarative_schema_changer session setting;disables new schema changer by default [off = 0, on = 1, unsafe = 2, unsafe_always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.vectorize
enumerationondefault vectorize mode [on = 0, on = 1, on = 2, experimental_always = 3, off = 4]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.zigzag_join.enabled
booleanfalsedefault value for enable_zigzag_join session setting; disallows use of zig-zag join by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.distsql.temp_storage.workmem
byte size64 MiBmaximum amount of memory in bytes a processor can use before falling back to temp storageServerless/Dedicated/Self-Hosted
sql.guardrails.max_row_size_err
byte size512 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an error is returned; use 0 to disableServerless/Dedicated/Self-Hosted
sql.guardrails.max_row_size_log
byte size64 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an event is logged to SQL_PERF (or SQL_INTERNAL_PERF if the mutating statement was internal); use 0 to disableServerless/Dedicated/Self-Hosted
sql.hash_sharded_range_pre_split.max
integer16max pre-split ranges to have when adding hash sharded index to an existing tableServerless/Dedicated/Self-Hosted
sql.index_recommendation.drop_unused_duration
duration168h0m0sthe index unused duration at which we begin to recommend dropping the indexServerless/Dedicated/Self-Hosted
sql.insights.anomaly_detection.enabled
booleantrueenable per-fingerprint latency recording and anomaly detectionServerless/Dedicated/Self-Hosted
sql.insights.anomaly_detection.latency_threshold
duration50msstatements must surpass this threshold to trigger anomaly detection and identificationServerless/Dedicated/Self-Hosted
sql.insights.anomaly_detection.memory_limit
byte size1.0 MiBthe maximum amount of memory allowed for tracking statement latenciesServerless/Dedicated/Self-Hosted
sql.insights.execution_insights_capacity
integer1000the size of the per-node store of execution insightsServerless/Dedicated/Self-Hosted
sql.insights.high_retry_count.threshold
integer10the number of retries a slow statement must have undergone for its high retry count to be highlighted as a potential problemServerless/Dedicated/Self-Hosted
sql.insights.latency_threshold
duration100msamount of time after which an executing statement is considered slow. Use 0 to disable.Serverless/Dedicated/Self-Hosted
sql.log.redact_names.enabled
booleanfalseif set, schema object identifers are redacted in SQL statements that appear in event logsServerless/Dedicated/Self-Hosted
sql.log.slow_query.experimental_full_table_scans.enabled
booleanfalsewhen set to true, statements that perform a full table/index scan will be logged to the slow query log even if they do not meet the latency threshold. Must have the slow query log enabled for this setting to have any effect.Serverless/Dedicated/Self-Hosted
sql.log.slow_query.internal_queries.enabled
booleanfalsewhen set to true, internal queries which exceed the slow query log threshold are logged to a separate log. Must have the slow query log enabled for this setting to have any effect.Serverless/Dedicated/Self-Hosted
sql.log.slow_query.latency_threshold
duration0swhen set to non-zero, log statements whose service latency exceeds the threshold to a secondary logger on each nodeServerless/Dedicated/Self-Hosted
sql.log.user_audit
stringuser/role-based audit logging configuration. An enterprise license is required for this cluster setting to take effect.Serverless/Dedicated/Self-Hosted
sql.log.user_audit.reduced_config.enabled
booleanfalseenables logic to compute a reduced audit configuration, computing the audit configuration only once at session start instead of at each SQL event. The tradeoff with the increase in performance (~5%), is that changes to the audit configuration (user role memberships/cluster setting) are not reflected within session. Users will need to start a new session to see these changes in their auditing behaviour.Serverless/Dedicated/Self-Hosted
sql.metrics.index_usage_stats.enabled
booleantruecollect per index usage statisticsServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_reported_stmt_fingerprints
integer100000the maximum number of reported statement fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_reported_txn_fingerprints
integer100000the maximum number of reported transaction fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_stmt_fingerprints
integer7500the maximum number of statement fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_txn_fingerprints
integer7500the maximum number of transaction fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.dump_to_logs.enabled
(alias: sql.metrics.statement_details.dump_to_logs)
booleanfalsedump collected statement statistics to node logs when periodically clearedServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.enabled
booleantruecollect per-statement query statisticsServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.gateway_node.enabled
booleanfalsesave the gateway node for each statement fingerprint. If false, the value will be stored as 0.Serverless/Dedicated/Self-Hosted
sql.metrics.statement_details.index_recommendation_collection.enabled
booleantruegenerate an index recommendation for each fingerprint IDServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.max_mem_reported_idx_recommendations
integer5000the maximum number of reported index recommendation info stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.plan_collection.enabled
booleanfalseperiodically save a logical plan for each fingerprintServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.plan_collection.period
duration5m0sthe time until a new logical plan is collectedServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.threshold
duration0sminimum execution time to cause statement statistics to be collected. If configured, no transaction stats are collected.Serverless/Dedicated/Self-Hosted
sql.metrics.transaction_details.enabled
booleantruecollect per-application transaction statisticsServerless/Dedicated/Self-Hosted
sql.multiple_modifications_of_table.enabled
booleanfalseif true, allow statements containing multiple INSERT ON CONFLICT, UPSERT, UPDATE, or DELETE subqueries modifying the same table, at the risk of data corruption if the same row is modified multiple times by a single statement (multiple INSERT subqueries without ON CONFLICT cannot cause corruption and are always allowed)Serverless/Dedicated/Self-Hosted
sql.multiregion.drop_primary_region.enabled
booleantrueallows dropping the PRIMARY REGION of a database if it is the last regionServerless/Dedicated/Self-Hosted
sql.notices.enabled
booleantrueenable notices in the server/client protocol being sentServerless/Dedicated/Self-Hosted
sql.optimizer.uniqueness_checks_for_gen_random_uuid.enabled
booleanfalseif enabled, uniqueness checks may be planned for mutations of UUID columns updated with gen_random_uuid(); otherwise, uniqueness is assumed due to near-zero collision probabilityServerless/Dedicated/Self-Hosted
sql.schema.telemetry.recurrence
string@weeklycron-tab recurrence for SQL schema telemetry jobDedicated/Self-hosted (read-write); Serverless (read-only)
sql.spatial.experimental_box2d_comparison_operators.enabled
booleanfalseenables the use of certain experimental box2d comparison operatorsServerless/Dedicated/Self-Hosted
sql.stats.activity.persisted_rows.max
integer200000maximum number of rows of statement and transaction activity that will be persisted in the system tablesServerless/Dedicated/Self-Hosted
sql.stats.automatic_collection.enabled
booleantrueautomatic statistics collection modeServerless/Dedicated/Self-Hosted
sql.stats.automatic_collection.fraction_stale_rows
float0.2target fraction of stale rows per table that will trigger a statistics refreshServerless/Dedicated/Self-Hosted
sql.stats.automatic_collection.min_stale_rows
integer500target minimum number of stale rows per table that will trigger a statistics refreshServerless/Dedicated/Self-Hosted
sql.stats.automatic_partial_collection.enabled
booleantrueautomatic partial statistics collection modeServerless/Dedicated/Self-Hosted
sql.stats.automatic_partial_collection.fraction_stale_rows
float0.05target fraction of stale rows per table that will trigger a partial statistics refreshServerless/Dedicated/Self-Hosted
sql.stats.automatic_partial_collection.min_stale_rows
integer100target minimum number of stale rows per table that will trigger a partial statistics refreshServerless/Dedicated/Self-Hosted
sql.stats.cleanup.recurrence
string@hourlycron-tab recurrence for SQL Stats cleanup jobServerless/Dedicated/Self-Hosted
sql.stats.error_on_concurrent_create_stats.enabled
booleantrueset to true to error on concurrent CREATE STATISTICS jobs, instead of skipping themServerless/Dedicated/Self-Hosted
sql.stats.flush.enabled
booleantrueif set, SQL execution statistics are periodically flushed to diskServerless/Dedicated/Self-Hosted
sql.stats.flush.interval
duration10m0sthe interval at which SQL execution statistics are flushed to disk, this value must be less than or equal to 1 hourServerless/Dedicated/Self-Hosted
sql.stats.forecasts.enabled
booleantruewhen true, enables generation of statistics forecasts by default for all tablesServerless/Dedicated/Self-Hosted
sql.stats.forecasts.max_decrease
float0.3333333333333333the most a prediction is allowed to decrease, expressed as the minimum ratio of the prediction to the lowest prior observationServerless/Dedicated/Self-Hosted
sql.stats.forecasts.min_goodness_of_fit
float0.95the minimum R² (goodness of fit) measurement required from all predictive models to use a forecastServerless/Dedicated/Self-Hosted
sql.stats.forecasts.min_observations
integer3the mimimum number of observed statistics required to produce a statistics forecastServerless/Dedicated/Self-Hosted
sql.stats.histogram_buckets.count
integer200maximum number of histogram buckets to build during table statistics collectionServerless/Dedicated/Self-Hosted
sql.stats.histogram_buckets.include_most_common_values.enabled
booleantruewhether to include most common values as histogram bucketsServerless/Dedicated/Self-Hosted
sql.stats.histogram_buckets.max_fraction_most_common_values
float0.1maximum fraction of histogram buckets to use for most common valuesServerless/Dedicated/Self-Hosted
sql.stats.histogram_collection.enabled
booleantruehistogram collection modeServerless/Dedicated/Self-Hosted
sql.stats.histogram_samples.count
integer0number of rows sampled for histogram construction during table statistics collection. Not setting this or setting a value of 0 means that a reasonable sample size will be automatically picked based on the table size.Serverless/Dedicated/Self-Hosted
sql.stats.multi_column_collection.enabled
booleantruemulti-column statistics collection modeServerless/Dedicated/Self-Hosted
sql.stats.non_default_columns.min_retention_period
duration24h0m0sminimum retention period for table statistics collected on non-default columnsServerless/Dedicated/Self-Hosted
sql.stats.non_indexed_json_histograms.enabled
booleanfalseset to true to collect table statistics histograms on non-indexed JSON columnsServerless/Dedicated/Self-Hosted
sql.stats.persisted_rows.max
integer1000000maximum number of rows of statement and transaction statistics that will be persisted in the system tables before compaction beginsServerless/Dedicated/Self-Hosted
sql.stats.post_events.enabled
booleanfalseif set, an event is logged for every successful CREATE STATISTICS jobServerless/Dedicated/Self-Hosted
sql.stats.response.max
integer20000the maximum number of statements and transaction stats returned in a CombinedStatements requestServerless/Dedicated/Self-Hosted
sql.stats.response.show_internal.enabled
booleanfalsecontrols if statistics for internal executions should be returned by the CombinedStatements and if internal sessions should be returned by the ListSessions endpoints. These endpoints are used to display statistics on the SQL Activity pagesServerless/Dedicated/Self-Hosted
sql.stats.system_tables.enabled
booleantruewhen true, enables use of statistics on system tables by the query optimizerServerless/Dedicated/Self-Hosted
sql.stats.system_tables_autostats.enabled
booleantruewhen true, enables automatic collection of statistics on system tablesServerless/Dedicated/Self-Hosted
sql.stats.virtual_computed_columns.enabled
booleantrueset to true to collect table statistics on virtual computed columnsServerless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.enabled
booleanfalsewhen set to true, executed queries will emit an event on the telemetry logging channelServerless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.internal.enabled
booleanfalsewhen set to true, internal queries will be sampled in telemetry loggingServerless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample executions for telemetry, note that it is recommended that this value shares a log-line limit of 10 logs per second on the telemetry pipeline with all other telemetry events. If sampling mode is set to 'transaction', this value is ignored.Serverless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.mode
enumerationstatementthe execution level used for telemetry sampling. If set to 'statement', events are sampled at the statement execution level. If set to 'transaction', events are sampled at the transaction execution level, i.e. all statements for a transaction will be logged and are counted together as one sampled event (events are still emitted one per statement). [statement = 0, transaction = 1]Serverless/Dedicated/Self-Hosted
sql.telemetry.transaction_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample transactions for telemetry. If sampling mode is set to 'statement', this setting is ignored. In practice, this means that we only sample a transaction if 1/max_event_frequency seconds have elapsed since the last transaction was sampled.Serverless/Dedicated/Self-Hosted
sql.telemetry.transaction_sampling.statement_events_per_transaction.max
integer50the maximum number of statement events to log for every sampled transaction. Note that statements that are logged by force do not adhere to this limit.Serverless/Dedicated/Self-Hosted
sql.temp_object_cleaner.cleanup_interval
duration30m0show often to clean up orphaned temporary objectsServerless/Dedicated/Self-Hosted
sql.temp_object_cleaner.wait_interval
duration30m0show long after creation a temporary object will be cleaned upServerless/Dedicated/Self-Hosted
sql.log.all_statements.enabled
(alias: sql.trace.log_statement_execute)
booleanfalseset to true to enable logging of all executed statementsServerless/Dedicated/Self-Hosted
sql.trace.stmt.enable_threshold
duration0senables tracing on all statements; statements executing for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting applies to individual statements within a transaction and is therefore finer-grained than sql.trace.txn.enable_thresholdServerless/Dedicated/Self-Hosted
sql.trace.txn.enable_threshold
duration0senables tracing on all transactions; transactions open for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting is coarser-grained than sql.trace.stmt.enable_threshold because it applies to all statements within a transaction as well as client communication (e.g. retries)Serverless/Dedicated/Self-Hosted
sql.ttl.changefeed_replication.disabled
booleanfalseif true, deletes issued by TTL will not be replicated via changefeeds (this setting will be ignored by changefeeds that have the ignore_disable_changefeed_replication option set; such changefeeds will continue to replicate all TTL deletes)Serverless/Dedicated/Self-Hosted
sql.ttl.default_delete_batch_size
integer100default amount of rows to delete in a single query during a TTL jobServerless/Dedicated/Self-Hosted
sql.ttl.default_delete_rate_limit
integer100default delete rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Serverless/Dedicated/Self-Hosted
sql.ttl.default_select_batch_size
integer500default amount of rows to select in a single query during a TTL jobServerless/Dedicated/Self-Hosted
sql.ttl.default_select_rate_limit
integer0default select rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Serverless/Dedicated/Self-Hosted
sql.ttl.job.enabled
booleantruewhether the TTL job is enabledServerless/Dedicated/Self-Hosted
sql.txn.read_committed_isolation.enabled
booleantrueset to true to allow transactions to use the READ COMMITTED isolation level if specified by BEGIN/SET commandsServerless/Dedicated/Self-Hosted
sql.txn.repeatable_read_isolation.enabled
(alias: sql.txn.snapshot_isolation.enabled)
booleanfalseset to true to allow transactions to use the REPEATABLE READ isolation level if specified by BEGIN/SET commandsServerless/Dedicated/Self-Hosted
sql.txn_fingerprint_id_cache.capacity
integer100the maximum number of txn fingerprint IDs storedServerless/Dedicated/Self-Hosted
storage.columnar_blocks.enabled
booleantrueset to true to enable columnar-blocks to store KVs in a columnar formatDedicated/Self-hosted (read-write); Serverless (read-only)
storage.delete_compaction_excise.enabled
booleantrueset to false to direct Pebble to not partially excise sstables in delete-only compactionsDedicated/Self-hosted (read-write); Serverless (read-only)
storage.experimental.eventually_file_only_snapshots.enabled
booleantrueset to false to disable eventually-file-only-snapshots (kv.snapshot_receiver.excise.enabled must also be false)Dedicated/Self-Hosted
storage.ingest_split.enabled
booleantrueset to false to disable ingest-time splitting that lowers write-amplificationDedicated/Self-Hosted
storage.ingestion.value_blocks.enabled
booleantrueset to true to enable writing of value blocks in ingestion sstablesServerless/Dedicated/Self-Hosted
storage.max_sync_duration
duration20smaximum duration for disk operations; any operations that take longer than this setting trigger a warning log entry or process crashDedicated/Self-hosted (read-write); Serverless (read-only)
storage.max_sync_duration.fatal.enabled
booleantrueif true, fatal the process when a disk operation exceeds storage.max_sync_durationServerless/Dedicated/Self-Hosted
storage.sstable.compression_algorithm
enumerationsnappydetermines the compression algorithm to use when compressing sstable data blocks for use in a Pebble store; [snappy = 1, zstd = 2, none = 3]Dedicated/Self-hosted (read-write); Serverless (read-only)
storage.sstable.compression_algorithm_backup_storage
enumerationsnappydetermines the compression algorithm to use when compressing sstable data blocks for backup row data storage; [snappy = 1, zstd = 2, none = 3]Dedicated/Self-hosted (read-write); Serverless (read-only)
storage.sstable.compression_algorithm_backup_transport
enumerationsnappydetermines the compression algorithm to use when compressing sstable data blocks for backup transport; [snappy = 1, zstd = 2, none = 3]Dedicated/Self-hosted (read-write); Serverless (read-only)
storage.wal_failover.unhealthy_op_threshold
duration100msthe latency of a WAL write considered unhealthy and triggers a failover to a secondary WAL locationDedicated/Self-Hosted
timeseries.storage.enabled
booleantrueif set, periodic timeseries data is stored within the cluster; disabling is not recommended unless you are storing the data elsewhereDedicated/Self-Hosted
timeseries.storage.resolution_10s.ttl
duration240h0m0sthe maximum age of time series data stored at the 10 second resolution. Data older than this is subject to rollup and deletion.Dedicated/Self-hosted (read-write); Serverless (read-only)
timeseries.storage.resolution_30m.ttl
duration2160h0m0sthe maximum age of time series data stored at the 30 minute resolution. Data older than this is subject to deletion.Dedicated/Self-hosted (read-write); Serverless (read-only)
trace.debug_http_endpoint.enabled
(alias: trace.debug.enable)
booleanfalseif set, traces for recent requests can be seen at https://<ui>/debug/requestsServerless/Dedicated/Self-Hosted
trace.opentelemetry.collector
stringaddress of an OpenTelemetry trace collector to receive traces using the otel gRPC protocol, as <host>:<port>. If no port is specified, 4317 will be used.Serverless/Dedicated/Self-Hosted
trace.snapshot.rate
duration0sif non-zero, interval at which background trace snapshots are capturedServerless/Dedicated/Self-Hosted
trace.span_registry.enabled
booleanfalseif set, ongoing traces can be seen at https://<ui>/#/debug/tracezServerless/Dedicated/Self-Hosted
trace.zipkin.collector
stringthe address of a Zipkin instance to receive traces, as <host>:<port>. If no port is specified, 9411 will be used.Serverless/Dedicated/Self-Hosted
ui.database_locality_metadata.enabled
booleantrueif enabled shows extended locality data about databases and tables in DB Console which can be expensive to computeServerless/Dedicated/Self-Hosted
ui.display_timezone
enumerationetc/utcthe timezone used to format timestamps in the ui [etc/utc = 0, america/new_york = 1]Serverless/Dedicated/Self-Hosted
version
version25.1set the active cluster version in the format '<major>.<minor>'Serverless/Dedicated/Self-Hosted
diff --git a/src/current/_includes/cockroach-generated/release-25.1/sql/aggregates.md b/src/current/_includes/cockroach-generated/release-25.1/sql/aggregates.md new file mode 100644 index 00000000000..3213f0f02a8 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.1/sql/aggregates.md @@ -0,0 +1,579 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_agg(arg1: bool) → bool[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bool[]) → bool[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes) → bytes[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes[]) → bytes[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date) → date[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date[]) → date[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal) → decimal[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal[]) → decimal[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float) → float[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float[]) → float[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet) → inet[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet[]) → inet[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int) → int[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int[]) → int[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval) → interval[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval[]) → interval[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string) → string[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string[]) → string[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time) → time[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time[]) → time[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp) → timestamp[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp[]) → timestamp[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz) → timestamptz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz[]) → timestamptz[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid) → uuid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid[]) → uuid[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum) → anyenum[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum[]) → anyenum[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d) → box2d[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d[]) → box2d[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography) → geography[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography[]) → geography[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry) → geometry[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry[]) → geometry[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb) → jsonb[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb[]) → jsonb[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid) → oid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid[]) → oid[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn) → pg_lsn[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn[]) → pg_lsn[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor) → refcursor[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor[]) → refcursor[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz) → timetz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz[]) → timetz[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple) → tuple[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple[]) → tuple[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit) → varbit[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit[]) → varbit[][]

Aggregates the selected values into an array.

+		Immutable
array_cat_agg(arg1: bool[]) → bool[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: bytes[]) → bytes[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: date[]) → date[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: decimal[]) → decimal[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: float[]) → float[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: inet[]) → inet[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: int[]) → int[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: interval[]) → interval[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: string[]) → string[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: time[]) → time[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamp[]) → timestamp[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamptz[]) → timestamptz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: uuid[]) → uuid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: anyenum[]) → anyenum[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: box2d[]) → box2d[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geography[]) → geography[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geometry[]) → geometry[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: jsonb[]) → jsonb[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: oid[]) → oid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: pg_lsn[]) → pg_lsn[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: refcursor[]) → refcursor[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timetz[]) → timetz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: tuple[]) → tuple[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: varbit[]) → varbit[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
avg(arg1: decimal) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: float) → float

Calculates the average of the selected values.

+		Immutable
avg(arg1: int) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: interval) → interval

Calculates the average of the selected values.

+		Immutable
bit_and(arg1: int) → int

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_and(arg1: varbit) → varbit

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: int) → int

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: varbit) → varbit

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bool_and(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
bool_or(arg1: bool) → bool

Calculates the boolean value of ORing all selected values.

+		Immutable
concat_agg(arg1: bytes) → bytes

Concatenates all selected values.

+		Immutable
concat_agg(arg1: string) → string

Concatenates all selected values.

+		Immutable
corr(arg1: decimal, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
count(arg1: anyelement) → int

Calculates the number of selected elements.

+		Immutable
count_rows() → int

Calculates the number of rows.

+		Immutable
covar_pop(arg1: decimal, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
every(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
json_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
json_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
jsonb_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
jsonb_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
max(arg1: bool) → bool

Identifies the maximum selected value.

+		Immutable
max(arg1: bytes) → bytes

Identifies the maximum selected value.

+		Immutable
max(arg1: date) → date

Identifies the maximum selected value.

+		Immutable
max(arg1: decimal) → decimal

Identifies the maximum selected value.

+		Immutable
max(arg1: float) → float

Identifies the maximum selected value.

+		Immutable
max(arg1: inet) → inet

Identifies the maximum selected value.

+		Immutable
max(arg1: int) → int

Identifies the maximum selected value.

+		Immutable
max(arg1: interval) → interval

Identifies the maximum selected value.

+		Immutable
max(arg1: string) → string

Identifies the maximum selected value.

+		Immutable
max(arg1: time) → time

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamp) → timestamp

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamptz) → timestamptz

Identifies the maximum selected value.

+		Immutable
max(arg1: uuid) → uuid

Identifies the maximum selected value.

+		Immutable
max(arg1: anyenum) → anyenum

Identifies the maximum selected value.

+		Immutable
max(arg1: box2d) → box2d

Identifies the maximum selected value.

+		Immutable
max(arg1: collatedstring{*}) → collatedstring{*}

Identifies the maximum selected value.

+		Immutable
max(arg1: geography) → geography

Identifies the maximum selected value.

+		Immutable
max(arg1: geometry) → geometry

Identifies the maximum selected value.

+		Immutable
max(arg1: jsonb) → jsonb

Identifies the maximum selected value.

+		Immutable
max(arg1: oid) → oid

Identifies the maximum selected value.

+		Immutable
max(arg1: pg_lsn) → pg_lsn

Identifies the maximum selected value.

+		Immutable
max(arg1: timetz) → timetz

Identifies the maximum selected value.

+		Immutable
max(arg1: varbit) → varbit

Identifies the maximum selected value.

+		Immutable
min(arg1: bool) → bool

Identifies the minimum selected value.

+		Immutable
min(arg1: bytes) → bytes

Identifies the minimum selected value.

+		Immutable
min(arg1: date) → date

Identifies the minimum selected value.

+		Immutable
min(arg1: decimal) → decimal

Identifies the minimum selected value.

+		Immutable
min(arg1: float) → float

Identifies the minimum selected value.

+		Immutable
min(arg1: inet) → inet

Identifies the minimum selected value.

+		Immutable
min(arg1: int) → int

Identifies the minimum selected value.

+		Immutable
min(arg1: interval) → interval

Identifies the minimum selected value.

+		Immutable
min(arg1: string) → string

Identifies the minimum selected value.

+		Immutable
min(arg1: time) → time

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamp) → timestamp

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamptz) → timestamptz

Identifies the minimum selected value.

+		Immutable
min(arg1: uuid) → uuid

Identifies the minimum selected value.

+		Immutable
min(arg1: anyenum) → anyenum

Identifies the minimum selected value.

+		Immutable
min(arg1: box2d) → box2d

Identifies the minimum selected value.

+		Immutable
min(arg1: collatedstring{*}) → collatedstring{*}

Identifies the minimum selected value.

+		Immutable
min(arg1: geography) → geography

Identifies the minimum selected value.

+		Immutable
min(arg1: geometry) → geometry

Identifies the minimum selected value.

+		Immutable
min(arg1: jsonb) → jsonb

Identifies the minimum selected value.

+		Immutable
min(arg1: oid) → oid

Identifies the minimum selected value.

+		Immutable
min(arg1: pg_lsn) → pg_lsn

Identifies the minimum selected value.

+		Immutable
min(arg1: timetz) → timetz

Identifies the minimum selected value.

+		Immutable
min(arg1: varbit) → varbit

Identifies the minimum selected value.

+		Immutable
percentile_cont(arg1: float) → float

Continuous percentile: returns a float corresponding to the specified fraction in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float) → interval

Continuous percentile: returns an interval corresponding to the specified fraction in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_cont(arg1: float[]) → float[]

Continuous percentile: returns floats corresponding to the specified fractions in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float[]) → interval[]

Continuous percentile: returns intervals corresponding to the specified fractions in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_disc(arg1: float) → anyelement

Discrete percentile: returns the first input value whose position in the ordering equals or exceeds the specified fraction.

+		Immutable
percentile_disc(arg1: float[]) → anyelement

Discrete percentile: returns input values whose position in the ordering equals or exceeds the specified fractions.

+		Immutable
regr_avgx(arg1: decimal, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_count(arg1: decimal, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_intercept(arg1: decimal, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_r2(arg1: decimal, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_slope(arg1: decimal, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_sxx(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
sqrdiff(arg1: decimal) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: float) → float

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: int) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
st_collect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_extent(arg1: geometry) → box2d

Forms a Box2D that encapsulates all provided geometries.

+		Immutable
st_makeline(arg1: geometry) → geometry

Forms a LineString from Point, MultiPoint or LineStrings. Other shapes will be ignored.

+		Immutable
st_memcollect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_memunion(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
st_union(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
stddev(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: decimal) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: float) → float

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: int) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
string_agg(arg1: bytes, arg2: bytes) → bytes

Concatenates all selected values using the provided delimiter.

+		Immutable
string_agg(arg1: string, arg2: string) → string

Concatenates all selected values using the provided delimiter.

+		Immutable
sum(arg1: decimal) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: float) → float

Calculates the sum of the selected values.

+		Immutable
sum(arg1: int) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: interval) → interval

Calculates the sum of the selected values.

+		Immutable
sum_int(arg1: int) → int

Calculates the sum of the selected values.

+		Immutable
var_pop(arg1: decimal) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: float) → float

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: int) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_samp(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
variance(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
xor_agg(arg1: bytes) → bytes

Calculates the bitwise XOR of the selected values.

+		Immutable
xor_agg(arg1: int) → int

Calculates the bitwise XOR of the selected values.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-25.1/sql/functions.md b/src/current/_includes/cockroach-generated/release-25.1/sql/functions.md new file mode 100644 index 00000000000..1e734501429 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.1/sql/functions.md @@ -0,0 +1,3523 @@ +### Array functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_append(array: bool[], elem: bool) → bool[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: bytes[], elem: bytes) → bytes[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: date[], elem: date) → date[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: decimal[], elem: decimal) → decimal[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: float[], elem: float) → float[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: inet[], elem: inet) → inet[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: int[], elem: int) → int[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: interval[], elem: interval) → interval[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: string[], elem: string) → string[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: time[], elem: time) → time[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamp[], elem: timestamp) → timestamp[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamptz[], elem: timestamptz) → timestamptz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: uuid[], elem: uuid) → uuid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: anyenum[], elem: anyenum) → anyenum[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: box2d[], elem: box2d) → box2d[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geography[], elem: geography) → geography[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geometry[], elem: geometry) → geometry[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: jsonb[], elem: jsonb) → jsonb[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: oid[], elem: oid) → oid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: refcursor[], elem: refcursor) → refcursor[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timetz[], elem: timetz) → timetz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: tuple[], elem: tuple) → tuple[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: varbit[], elem: varbit) → varbit[]

Appends elem to array, returning the result.

+		Immutable
array_cat(left: bool[], right: bool[]) → bool[]

Appends two arrays.

+		Immutable
array_cat(left: bytes[], right: bytes[]) → bytes[]

Appends two arrays.

+		Immutable
array_cat(left: date[], right: date[]) → date[]

Appends two arrays.

+		Immutable
array_cat(left: decimal[], right: decimal[]) → decimal[]

Appends two arrays.

+		Immutable
array_cat(left: float[], right: float[]) → float[]

Appends two arrays.

+		Immutable
array_cat(left: inet[], right: inet[]) → inet[]

Appends two arrays.

+		Immutable
array_cat(left: int[], right: int[]) → int[]

Appends two arrays.

+		Immutable
array_cat(left: interval[], right: interval[]) → interval[]

Appends two arrays.

+		Immutable
array_cat(left: string[], right: string[]) → string[]

Appends two arrays.

+		Immutable
array_cat(left: time[], right: time[]) → time[]

Appends two arrays.

+		Immutable
array_cat(left: timestamp[], right: timestamp[]) → timestamp[]

Appends two arrays.

+		Immutable
array_cat(left: timestamptz[], right: timestamptz[]) → timestamptz[]

Appends two arrays.

+		Immutable
array_cat(left: uuid[], right: uuid[]) → uuid[]

Appends two arrays.

+		Immutable
array_cat(left: anyenum[], right: anyenum[]) → anyenum[]

Appends two arrays.

+		Immutable
array_cat(left: box2d[], right: box2d[]) → box2d[]

Appends two arrays.

+		Immutable
array_cat(left: geography[], right: geography[]) → geography[]

Appends two arrays.

+		Immutable
array_cat(left: geometry[], right: geometry[]) → geometry[]

Appends two arrays.

+		Immutable
array_cat(left: jsonb[], right: jsonb[]) → jsonb[]

Appends two arrays.

+		Immutable
array_cat(left: oid[], right: oid[]) → oid[]

Appends two arrays.

+		Immutable
array_cat(left: pg_lsn[], right: pg_lsn[]) → pg_lsn[]

Appends two arrays.

+		Immutable
array_cat(left: refcursor[], right: refcursor[]) → refcursor[]

Appends two arrays.

+		Immutable
array_cat(left: timetz[], right: timetz[]) → timetz[]

Appends two arrays.

+		Immutable
array_cat(left: tuple[], right: tuple[]) → tuple[]

Appends two arrays.

+		Immutable
array_cat(left: varbit[], right: varbit[]) → varbit[]

Appends two arrays.

+		Immutable
array_length(input: anyelement[], array_dimension: int) → int

Calculates the length of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_lower(input: anyelement[], array_dimension: int) → int

Calculates the minimum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_position(array: bool[], elem: bool) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bool[], elem: bool, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: bytes[], elem: bytes) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bytes[], elem: bytes, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: date[], elem: date) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: date[], elem: date, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: decimal[], elem: decimal) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: decimal[], elem: decimal, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: float[], elem: float) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: float[], elem: float, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: inet[], elem: inet) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: inet[], elem: inet, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: int[], elem: int) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: int[], elem: int, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: interval[], elem: interval) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: interval[], elem: interval, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: string[], elem: string) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: string[], elem: string, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: time[], elem: time) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: time[], elem: time, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timestamp[], elem: timestamp) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamp[], elem: timestamp, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: uuid[], elem: uuid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: uuid[], elem: uuid, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: anyenum[], elem: anyenum) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: anyenum[], elem: anyenum, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: box2d[], elem: box2d) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: box2d[], elem: box2d, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: geography[], elem: geography) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geography[], elem: geography, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: geometry[], elem: geometry) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geometry[], elem: geometry, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: jsonb[], elem: jsonb) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: jsonb[], elem: jsonb, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: oid[], elem: oid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: oid[], elem: oid, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: refcursor[], elem: refcursor) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: refcursor[], elem: refcursor, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timetz[], elem: timetz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timetz[], elem: timetz, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: tuple[], elem: tuple) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: tuple[], elem: tuple, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: varbit[], elem: varbit) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: varbit[], elem: varbit, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_positions(array: bool[], elem: bool) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: bytes[], elem: bytes) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: date[], elem: date) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: decimal[], elem: decimal) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: float[], elem: float) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: inet[], elem: inet) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: int[], elem: int) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: interval[], elem: interval) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: string[], elem: string) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: time[], elem: time) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamp[], elem: timestamp) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamptz[], elem: timestamptz) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: uuid[], elem: uuid) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: anyenum[], elem: anyenum) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: box2d[], elem: box2d) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geography[], elem: geography) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geometry[], elem: geometry) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: jsonb[], elem: jsonb) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: oid[], elem: oid) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: pg_lsn[], elem: pg_lsn) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: refcursor[], elem: refcursor) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timetz[], elem: timetz) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: tuple[], elem: tuple) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: varbit[], elem: varbit) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_prepend(elem: bool, array: bool[]) → bool[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: bytes, array: bytes[]) → bytes[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: date, array: date[]) → date[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: decimal, array: decimal[]) → decimal[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: float, array: float[]) → float[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: inet, array: inet[]) → inet[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: int, array: int[]) → int[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: interval, array: interval[]) → interval[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: string, array: string[]) → string[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: time, array: time[]) → time[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamp, array: timestamp[]) → timestamp[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamptz, array: timestamptz[]) → timestamptz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: uuid, array: uuid[]) → uuid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: anyenum, array: anyenum[]) → anyenum[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: box2d, array: box2d[]) → box2d[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geography, array: geography[]) → geography[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geometry, array: geometry[]) → geometry[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: jsonb, array: jsonb[]) → jsonb[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: oid, array: oid[]) → oid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: pg_lsn, array: pg_lsn[]) → pg_lsn[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: refcursor, array: refcursor[]) → refcursor[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timetz, array: timetz[]) → timetz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: tuple, array: tuple[]) → tuple[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: varbit, array: varbit[]) → varbit[]

Prepends elem to array, returning the result.

+		Immutable
array_remove(array: bool[], elem: bool) → bool[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: bytes[], elem: bytes) → bytes[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: date[], elem: date) → date[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: decimal[], elem: decimal) → decimal[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: float[], elem: float) → float[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: inet[], elem: inet) → inet[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: int[], elem: int) → int[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: interval[], elem: interval) → interval[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: string[], elem: string) → string[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: time[], elem: time) → time[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamp[], elem: timestamp) → timestamp[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamptz[], elem: timestamptz) → timestamptz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: uuid[], elem: uuid) → uuid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: anyenum[], elem: anyenum) → anyenum[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: box2d[], elem: box2d) → box2d[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geography[], elem: geography) → geography[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geometry[], elem: geometry) → geometry[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: jsonb[], elem: jsonb) → jsonb[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: oid[], elem: oid) → oid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: refcursor[], elem: refcursor) → refcursor[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timetz[], elem: timetz) → timetz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: tuple[], elem: tuple) → tuple[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: varbit[], elem: varbit) → varbit[]

Remove from array all elements equal to elem.

+		Immutable
array_replace(array: bool[], toreplace: bool, replacewith: bool) → bool[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: bytes[], toreplace: bytes, replacewith: bytes) → bytes[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: date[], toreplace: date, replacewith: date) → date[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: decimal[], toreplace: decimal, replacewith: decimal) → decimal[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: float[], toreplace: float, replacewith: float) → float[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: inet[], toreplace: inet, replacewith: inet) → inet[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: int[], toreplace: int, replacewith: int) → int[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: interval[], toreplace: interval, replacewith: interval) → interval[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: string[], toreplace: string, replacewith: string) → string[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: time[], toreplace: time, replacewith: time) → time[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamp[], toreplace: timestamp, replacewith: timestamp) → timestamp[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamptz[], toreplace: timestamptz, replacewith: timestamptz) → timestamptz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: uuid[], toreplace: uuid, replacewith: uuid) → uuid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: anyenum[], toreplace: anyenum, replacewith: anyenum) → anyenum[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: box2d[], toreplace: box2d, replacewith: box2d) → box2d[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geography[], toreplace: geography, replacewith: geography) → geography[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geometry[], toreplace: geometry, replacewith: geometry) → geometry[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: jsonb[], toreplace: jsonb, replacewith: jsonb) → jsonb[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: oid[], toreplace: oid, replacewith: oid) → oid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: pg_lsn[], toreplace: pg_lsn, replacewith: pg_lsn) → pg_lsn[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: refcursor[], toreplace: refcursor, replacewith: refcursor) → refcursor[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timetz[], toreplace: timetz, replacewith: timetz) → timetz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: tuple[], toreplace: tuple, replacewith: tuple) → tuple[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: varbit[], toreplace: varbit, replacewith: varbit) → varbit[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_to_string(input: anyelement[], delim: string) → string

Join an array into a string with a delimiter.

+		Stable
array_to_string(input: anyelement[], delimiter: string, null: string) → string

Join an array into a string with a delimiter, replacing NULLs with a null string.

+		Stable
array_upper(input: anyelement[], array_dimension: int) → int

Calculates the maximum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
cardinality(input: anyelement[]) → int

Calculates the number of elements contained in input

+		Immutable
jsonb_array_to_string_array(input: jsonb) → string[]

Convert a JSONB array into a string array.

+		Immutable
string_to_array(str: string, delimiter: string) → string[]

Split a string into components on a delimiter.

+		Immutable
string_to_array(str: string, delimiter: string, null: string) → string[]

Split a string into components on a delimiter with a specified string to consider NULL.

+		Immutable
+ +### BOOL functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Matches case insensetively unescaped with pattern using escape as an escape token.

+		Immutable
inet_contained_by_or_equals(val: inet, container: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_contains_or_equals(container: inet, val: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_same_family(val: inet, val: inet) → bool

Checks if two IP addresses are of the same IP family.

+		Immutable
like_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
not_ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches case insensetively with pattern using escape as an escape token.

+		Immutable
not_like_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
not_similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
+ +### Comparison functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
greatest(anyelement...) → anyelement

Returns the element with the greatest value.

+		Immutable
least(anyelement...) → anyelement

Returns the element with the lowest value.

+		Immutable
num_nonnulls(anyelement...) → int

Returns the number of nonnull arguments.

+		Immutable
num_nulls(anyelement...) → int

Returns the number of null arguments.

+		Immutable
+ +### Cryptographic functions + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crypt(password: string, salt: string) → string

Generates a hash based on a password and salt. The hash algorithm and number of rounds if applicable are encoded in the salt.

+		Immutable
decrypt(data: bytes, key: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
decrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
digest(data: bytes, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
digest(data: string, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
encrypt(data: bytes, key: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
encrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
gen_random_bytes(count: int) → bytes

Returns count cryptographically strong random bytes. At most 1024 bytes can be extracted at a time.

+		Volatile
gen_salt(type: string) → string

Generates a salt for input into the crypt function using the default number of rounds.

+		Volatile
gen_salt(type: string, iter_count: int) → string

Generates a salt for input into the crypt function using iter_count number of rounds.

+		Volatile
hmac(data: bytes, key: bytes, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
hmac(data: string, key: string, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
+ +### DECIMAL functions + + + + + +
Function → ReturnsDescriptionVolatility
hlc_to_timestamp(hlc: decimal) → timestamptz

Returns a TimestampTZ representation of a CockroachDB HLC in decimal form.

+

Note that a TimestampTZ has less precision than a CockroachDB HLC. It is intended as +a convenience function to display HLCs in a print-friendly form. Use the decimal +value if you rely on the HLC for accuracy.

+		Immutable
+ +### Date and time functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
age(end: timestamptz, begin: timestamptz) → interval

Calculates the interval between begin and end, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use the timestamptz subtraction operator.

+		Immutable
age(val: timestamptz) → interval

Calculates the interval between val and the current time, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use now() - timestamptz.

+		Stable
clock_timestamp() → timestamp

Returns the current system time on one of the cluster nodes.

+		Volatile
clock_timestamp() → timestamptz

Returns the current system time on one of the cluster nodes.

+		Volatile
current_date() → date

Returns the date of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_timestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
date_part(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
date_part(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
date_trunc(element: string, input: date) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: interval) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: time) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero.

+

Compatible elements: hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamp) → timestamp

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamptz) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: timestamptz, timezone: string) → timestamptz

Truncates input to precision element in the specified timezone. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
experimental_follower_read_timestamp() → timestamptz

Same as follower_read_timestamp. This name is deprecated.

+		Volatile
experimental_strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
extract(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
extract(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
extract_duration(element: string, input: interval) → int

Extracts element from input. +Compatible elements: hour, minute, second, millisecond, microsecond. +This is deprecated in favor of extract which supports duration.

+		Immutable
follower_read_timestamp() → timestamptz

Returns a timestamp which is very likely to be safe to perform +against a follower replica.

+

This function is intended to be used with an AS OF SYSTEM TIME clause to perform +historical reads against a time which is recent but sufficiently old for reads +to be performed against the closest replica as opposed to the currently +leaseholder for a given range.

+

Note that this function requires an enterprise license on a CCL distribution to +return a result that is less likely the closest replica. It is otherwise +hardcoded as -4.8s from the statement time, which may not result in reading from the +nearest replica.

+		Volatile
localtimestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
make_date(year: int, month: int, day: int) → date

Create date (formatted according to ISO 8601) from year, month, and day fields (negative years signify BC).

+		Immutable
make_timestamp(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamp

Create timestamp (formatted according to ISO 8601) from year, month, day, hour, minute, and seconds fields (negative years signify BC).

+		Immutable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float, timezone: string) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
now() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
overlaps(s1: date, e1: date, s1: date, e2: date) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: date, e1: interval, s1: date, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: interval, s1: time, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: time, s1: time, e2: time) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: interval, s1: timestamp, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: timestamp, s1: timestamp, e2: timestamp) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamptz, e1: interval, s1: timestamptz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Stable
overlaps(s1: timestamptz, e1: timestamptz, s1: timestamptz, e2: timestamptz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: interval, s1: timetz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: timetz, s1: timetz, e2: timetz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
statement_timestamp() → timestamp

Returns the start time of the current statement.

+		Stable
statement_timestamp() → timestamptz

Returns the start time of the current statement.

+		Stable
strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
timeofday() → string

Returns the current system time on one of the cluster nodes as a string.

+		Stable
timezone(timezone: string, time: time) → timetz

Treat given time without time zone as located in the specified time zone.

+		Stable
timezone(timezone: string, timestamp: timestamp) → timestamptz

Treat given time stamp without time zone as located in the specified time zone.

+		Immutable
timezone(timezone: string, timestamptz: timestamptz) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Immutable
timezone(timezone: string, timestamptz_string: string) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Stable
timezone(timezone: string, timetz: timetz) → timetz

Convert given time with time zone to the new time zone.

+		Stable
to_char(date: date) → string

Convert an date to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(date: date, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_char(interval: interval) → string

Convert an interval to a string assuming the Postgres IntervalStyle.

+		Immutable
to_char(interval: interval, format: string) → string

Convert an interval to a string using the given format.

+		Stable
to_char(timestamp: timestamp) → string

Convert an timestamp to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(timestamp: timestamp, format: string) → string

Convert an timestamp to a string using the given format.

+		Stable
to_char(timestamptz: timestamptz, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_timestamp(timestamp: float) → timestamptz

Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to timestamp with time zone.

+		Immutable
transaction_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
with_max_staleness(max_staleness: interval) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_max_staleness(max_staleness: interval, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
+ +### Enum functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
enum_first(val: anyenum) → anyenum

Returns the first value of the input enum type.

+		Stable
enum_last(val: anyenum) → anyenum

Returns the last value of the input enum type.

+		Stable
enum_range(lower: anyenum, upper: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array between the two arguments (inclusive).

+		Stable
enum_range(val: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array.

+		Stable
+ +### FLOAT functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abs(val: decimal) → decimal

Calculates the absolute value of val.

+		Immutable
abs(val: float) → float

Calculates the absolute value of val.

+		Immutable
abs(val: int) → int

Calculates the absolute value of val.

+		Immutable
acos(val: float) → float

Calculates the inverse cosine of val.

+		Immutable
acosd(val: float) → float

Calculates the inverse cosine of val with the result in degrees

+		Immutable
acosh(val: float) → float

Calculates the inverse hyperbolic cosine of val.

+		Immutable
asin(val: float) → float

Calculates the inverse sine of val.

+		Immutable
asind(val: float) → float

Calculates the inverse sine of val with the result in degrees.

+		Immutable
asinh(val: float) → float

Calculates the inverse hyperbolic sine of val.

+		Immutable
atan(val: float) → float

Calculates the inverse tangent of val.

+		Immutable
atan2(x: float, y: float) → float

Calculates the inverse tangent of x/y.

+		Immutable
atan2d(x: float, y: float) → float

Calculates the inverse tangent of x/y with the result in degrees

+		Immutable
atand(val: float) → float

Calculates the inverse tangent of val with the result in degrees.

+		Immutable
atanh(val: float) → float

Calculates the inverse hyperbolic tangent of val.

+		Immutable
cbrt(val: decimal) → decimal

Calculates the cube root (∛) of val.

+		Immutable
cbrt(val: float) → float

Calculates the cube root (∛) of val.

+		Immutable
ceil(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
cos(val: float) → float

Calculates the cosine of val.

+		Immutable
cosd(val: float) → float

Calculates the cosine of val where val is in degrees.

+		Immutable
cosh(val: float) → float

Calculates the hyperbolic cosine of val.

+		Immutable
cot(val: float) → float

Calculates the cotangent of val.

+		Immutable
cotd(val: float) → float

Calculates the cotangent of val where val is in degrees.

+		Immutable
degrees(val: float) → float

Converts val as a radian value to a degree value.

+		Immutable
div(x: decimal, y: decimal) → decimal

Calculates the integer quotient of x/y.

+		Immutable
div(x: float, y: float) → float

Calculates the integer quotient of x/y.

+		Immutable
div(x: int, y: int) → int

Calculates the integer quotient of x/y.

+		Immutable
exp(val: decimal) → decimal

Calculates e ^ val.

+		Immutable
exp(val: float) → float

Calculates e ^ val.

+		Immutable
floor(val: decimal) → decimal

Calculates the largest integer not greater than val.

+		Immutable
floor(val: float) → float

Calculates the largest integer not greater than val.

+		Immutable
floor(val: int) → float

Calculates the largest integer not greater than val.

+		Immutable
isnan(val: decimal) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
isnan(val: float) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
ln(val: decimal) → decimal

Calculates the natural log of val.

+		Immutable
ln(val: float) → float

Calculates the natural log of val.

+		Immutable
log(b: decimal, x: decimal) → decimal

Calculates the base b log of val.

+		Immutable
log(b: float, x: float) → float

Calculates the base b log of val.

+		Immutable
log(val: decimal) → decimal

Calculates the base 10 log of val.

+		Immutable
log(val: float) → float

Calculates the base 10 log of val.

+		Immutable
mod(x: decimal, y: decimal) → decimal

Calculates x%y.

+		Immutable
mod(x: float, y: float) → float

Calculates x%y.

+		Immutable
mod(x: int, y: int) → int

Calculates x%y.

+		Immutable
pi() → float

Returns the value for pi (3.141592653589793).

+		Immutable
pow(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
pow(x: float, y: float) → float

Calculates x^y.

+		Immutable
pow(x: int, y: int) → int

Calculates x^y.

+		Immutable
power(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
power(x: float, y: float) → float

Calculates x^y.

+		Immutable
power(x: int, y: int) → int

Calculates x^y.

+		Immutable
radians(val: float) → float

Converts val as a degree value to a radians value.

+		Immutable
random() → float

Returns a random floating-point number between 0 (inclusive) and 1 (exclusive). Note that the value contains at most 53 bits of randomness.

+		Volatile
round(input: decimal, decimal_accuracy: int) → decimal

Keeps decimal_accuracy number of figures to the right of the zero position in input using half away from zero rounding. If decimal_accuracy is not in the range -2^31…(2^31-1), the results are undefined.

+		Immutable
round(input: float, decimal_accuracy: int) → float

Keeps decimal_accuracy number of figures to the right of the zero position in input using half to even (banker’s) rounding.

+		Immutable
round(val: decimal) → decimal

Rounds val to the nearest integer, half away from zero: round(+/-2.4) = +/-2, round(+/-2.5) = +/-3.

+		Immutable
round(val: float) → float

Rounds val to the nearest integer using half to even (banker’s) rounding.

+		Immutable
setseed(seed: float) → void

Sets the seed for subsequent random() calls in this session (value between -1.0 and 1.0, inclusive). There are no guarantees as to how this affects the seed of random() calls that appear in the same query as setseed().

+		Volatile
sign(val: decimal) → decimal

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: float) → float

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: int) → int

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sin(val: float) → float

Calculates the sine of val.

+		Immutable
sind(val: float) → float

Calculates the sine of val where val is in degrees.

+		Immutable
sinh(val: float) → float

Calculates the hyperbolic sine of val.

+		Immutable
sqrt(val: decimal) → decimal

Calculates the square root of val.

+		Immutable
sqrt(val: float) → float

Calculates the square root of val.

+		Immutable
tan(val: float) → float

Calculates the tangent of val.

+		Immutable
tand(val: float) → float

Calculates the tangent of val where val is in degrees.

+		Immutable
tanh(val: float) → float

Calculates the hyperbolic tangent of val.

+		Immutable
trunc(val: decimal) → decimal

Truncates the decimal values of val.

+		Immutable
trunc(val: decimal, scale: int) → decimal

Truncate val to scale decimal places

+		Immutable
trunc(val: float) → float

Truncates the decimal values of val.

+		Immutable
+ +### Full Text Search functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
phraseto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The <-> operator is inserted between each token in the input.

+		Immutable
phraseto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The <-> operator is inserted between each token in the input.

+		Stable
plainto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The & operator is inserted between each token in the input.

+		Immutable
plainto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The & operator is inserted between each token in the input.

+		Stable
to_tsquery(config: string, text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the specified configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Immutable
to_tsquery(text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the default configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Stable
to_tsvector(config: string, text: string) → tsvector

Converts text to a tsvector, normalizing words according to the specified configuration. Position information is included in the result.

+		Immutable
to_tsvector(text: string) → tsvector

Converts text to a tsvector, normalizing words according to the default configuration. Position information is included in the result.

+		Stable
ts_parse(parser_name: string, document: string) → tuple{int AS tokid, string AS token}

ts_parse parses the given document and returns a series of records, one for each token produced by parsing. Each record includes a tokid showing the assigned token type and a token which is the text of the token.

+		Stable
ts_rank(vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
+ +### Fuzzy String Matching functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
levenshtein(source: string, target: string) → int

Calculates the Levenshtein distance between two strings. Maximum input length is 255 characters.

+		Immutable
levenshtein(source: string, target: string, ins_cost: int, del_cost: int, sub_cost: int) → int

Calculates the Levenshtein distance between two strings. The cost parameters specify how much to charge for each edit operation. Maximum input length is 255 characters.

+		Immutable
metaphone(source: string, max_output_length: int) → string

Convert a string to its Metaphone code. Maximum input length is 255 characters

+		Immutable
soundex(source: string) → string

Convert a string to its Soundex code.

+		Immutable
+ +### ID generation functions + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
experimental_uuid_v4() → bytes

Returns a UUID.

+		Volatile
gen_random_ulid() → uuid

Generates a random ULID and returns it as a value of UUID type.

+		Volatile
gen_random_uuid() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
unique_rowid() → int

Returns a unique ID used by CockroachDB to generate unique row IDs if a Primary Key isn’t defined for the table. The value is a combination of the insert timestamp and the ID of the node executing the statement, which guarantees this combination is globally unique. However, there can be gaps and the order is not completely guaranteed.

+		Volatile
unordered_unique_rowid() → int

Returns a unique ID. The value is a combination of the insert timestamp (bit-reversed) and the ID of the node executing the statement, which guarantees this combination is globally unique. The way it is generated is statistically likely to not have any ordering relative to previously generated values.

+		Volatile
uuid_generate_v1() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. To avoid exposing the server’s real MAC address, this uses a random MAC address and a timestamp. Essentially, this is an alias for uuid_generate_v1mc.

+		Volatile
uuid_generate_v1mc() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. This uses a random MAC address and a timestamp.

+		Volatile
uuid_generate_v3(namespace: uuid, name: string) → uuid

Generates a version 3 UUID in the given namespace using the specified input name, with md5 as the hashing method. The namespace should be one of the special constants produced by the uuid_ns_*() functions.

+		Immutable
uuid_generate_v4() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
uuid_generate_v5(namespace: uuid, name: string) → uuid

Generates a version 5 UUID in the given namespace using the specified input name. This is similar to a version 3 UUID, except it uses SHA-1 for hashing.

+		Immutable
uuid_nil() → uuid

Returns a nil UUID constant.

+		Immutable
uuid_ns_dns() → uuid

Returns a constant designating the DNS namespace for UUIDs.

+		Immutable
uuid_ns_oid() → uuid

Returns a constant designating the ISO object identifier (OID) namespace for UUIDs. These are unrelated to the OID type used internally in the database.

+		Immutable
uuid_ns_url() → uuid

Returns a constant designating the URL namespace for UUIDs.

+		Immutable
uuid_ns_x500() → uuid

Returns a constant designating the X.500 distinguished name (DN) namespace for UUIDs.

+		Immutable
uuid_v4() → bytes

Returns a UUID.

+		Volatile
+ +### INET functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abbrev(val: inet) → string

Converts the combined IP address and prefix length to an abbreviated display format as text.For INET types, this will omit the prefix length if it’s not the default (32 or IPv4, 128 for IPv6)

+

For example, abbrev('192.168.1.2/24') returns '192.168.1.2/24'

+		Immutable
broadcast(val: inet) → inet

Gets the broadcast address for the network address represented by the value.

+

For example, broadcast('192.168.1.2/24') returns '192.168.1.255/24'

+		Immutable
family(val: inet) → int

Extracts the IP family of the value; 4 for IPv4, 6 for IPv6.

+

For example, family('::1') returns 6

+		Immutable
host(val: inet) → string

Extracts the address part of the combined address/prefixlen value as text.

+

For example, host('192.168.1.2/16') returns '192.168.1.2'

+		Immutable
hostmask(val: inet) → inet

Creates an IP host mask corresponding to the prefix length in the value.

+

For example, hostmask('192.168.1.2/16') returns '0.0.255.255'

+		Immutable
masklen(val: inet) → int

Retrieves the prefix length stored in the value.

+

For example, masklen('192.168.1.2/16') returns 16

+		Immutable
netmask(val: inet) → inet

Creates an IP network mask corresponding to the prefix length in the value.

+

For example, netmask('192.168.1.2/16') returns '255.255.0.0'

+		Immutable
set_masklen(val: inet, prefixlen: int) → inet

Sets the prefix length of val to prefixlen.

+

For example, set_masklen('192.168.1.2', 16) returns '192.168.1.2/16'.

+		Immutable
+ +### INT functions + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crc32c(bytes...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32c(string...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32ieee(bytes...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
crc32ieee(string...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
fnv32(bytes...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32(string...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32a(bytes...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv32a(string...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64(bytes...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64(string...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64a(bytes...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64a(string...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
width_bucket(operand: decimal, b1: decimal, b2: decimal, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2.

+		Immutable
width_bucket(operand: int, b1: int, b2: int, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2.

+		Immutable
width_bucket(operand: anyelement, thresholds: anyelement[]) → int

return the bucket number to which operand would be assigned given an array listing the lower bounds of the buckets; returns 0 for an input less than the first lower bound; the thresholds array must be sorted, smallest first, or unexpected results will be obtained

+		Immutable
+ +### JSONB functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_to_json(array: anyelement[]) → jsonb

Returns the array as JSON or JSONB.

+		Stable
array_to_json(array: anyelement[], pretty_bool: bool) → jsonb

Returns the array as JSON or JSONB.

+		Stable
json_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
json_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
json_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
json_build_array(anyelement...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
json_build_object(anyelement...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
json_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
json_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
json_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
json_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
json_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
json_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
json_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
json_remove_path(val: jsonb, path: string[]) → jsonb

Remove the specified path from the JSON object.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
json_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
json_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
json_valid(string: string) → bool

Returns whether the given string is a valid JSON or not

+		Immutable
jsonb_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
jsonb_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
jsonb_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
jsonb_build_array(anyelement...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
jsonb_build_object(anyelement...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
jsonb_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
jsonb_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
jsonb_exists_any(json: jsonb, array: string[]) → bool

Returns whether any of the strings in the text array exist as top-level keys or array elements

+		Immutable
jsonb_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments. new_val will be inserted before path target.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb, insert_after: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If insert_after is true (default is false), new_val will be inserted after path target.

+		Immutable
jsonb_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
jsonb_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
jsonb_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
jsonb_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
jsonb_pretty(val: jsonb) → string

Returns the given JSON value as a STRING indented and with newlines.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
jsonb_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
jsonb_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
row_to_json(row: tuple) → jsonb

Returns the row as a JSON object.

+		Stable
to_json(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
to_jsonb(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
+ +### Multi-region functions + + + + + + + +
Function → ReturnsDescriptionVolatility
default_to_database_primary_region(val: string) → string

Returns the given region if the region has been added to the current database. +Otherwise, this will return the primary region of the current database. +This will error if the current database is not a multi-region database.

+		Stable
gateway_region() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
rehome_row() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
+ +### PGVector functions + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cosine_distance(v1: vector, v2: vector) → float

Returns the cosine distance between the two vectors.

+		Immutable
inner_product(v1: vector, v2: vector) → float

Returns the inner product between the two vectors.

+		Immutable
l1_distance(v1: vector, v2: vector) → float

Returns the Manhattan distance between the two vectors.

+		Immutable
l2_distance(v1: vector, v2: vector) → float

Returns the Euclidean distance between the two vectors.

+		Immutable
vector_dims(vector: vector) → int

Returns the number of the dimensions in the vector.

+		Immutable
vector_norm(vector: vector) → float

Returns the Euclidean norm of the vector.

+		Immutable
+ +### STRING[] functions + + + + + + +
Function → ReturnsDescriptionVolatility
regexp_split_to_array(string: string, pattern: string) → string[]

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_array(string: string, pattern: string, flags: string) → string[]

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
+ +### Sequence functions + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
currval(sequence_name: string) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
currval(sequence_name: regclass) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
lastval() → int

Return value most recently obtained with nextval in this session.

+		Volatile
nextval(sequence_name: string) → int

Advances the given sequence and returns its new value.

+		Volatile
nextval(sequence_name: regclass) → int

Advances the given sequence and returns its new value.

+		Volatile
setval(sequence_name: string, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: string, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
setval(sequence_name: regclass, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: regclass, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
+ +### Set-returning functions + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
aclexplode(aclitems: string[]) → tuple{oid AS grantor, oid AS grantee, string AS privilege_type, bool AS is_grantable}

Produces a virtual table containing aclitem stuff (returns no rows as this feature is unsupported in CockroachDB)

+		Stable
generate_series(start: int, end: int) → int

Produces a virtual table containing the integer values from start to end, inclusive.

+		Immutable
generate_series(start: int, end: int, step: int) → int

Produces a virtual table containing the integer values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamp, end: timestamp, step: interval) → timestamp

Produces a virtual table containing the timestamp values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamptz, end: timestamptz, step: interval) → timestamptz

Produces a virtual table containing the timestampTZ values from start to end, inclusive, by increment of step.

+		Immutable
generate_subscripts(array: anyelement[]) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int, reverse: bool) → int

Returns a series comprising the given array’s subscripts.

+

When reverse is true, the series is returned in reverse order.

+		Immutable
information_schema._pg_expandarray(input: anyelement[]) → tuple{anyelement AS x, int AS n}

Returns the input array as a set of rows with an index

+		Immutable
json_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
json_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
json_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
jsonb_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
jsonb_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
jsonb_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
pg_get_keywords() → tuple{string AS word, string AS catcode, string AS catdesc}

Produces a virtual table containing the keywords known to the SQL parser.

+		Immutable
pg_options_to_table(options: string[]) → tuple{string AS option_name, string AS option_value}

Converts the options array format to a table.

+		Stable
regexp_split_to_table(string: string, pattern: string) → string

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_table(string: string, pattern: string, flags: string) → string

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
unnest(anyelement[], anyelement[], anyelement[]...) → tuple{anyelement AS unnest, anyelement AS unnest, anyelement AS unnest}

Returns the input arrays as a set of rows

+		Immutable
unnest(input: anyelement[]) → anyelement

Returns the input array as a set of rows

+		Immutable
workload_index_recs() → string

Returns set of index recommendations

+		Immutable
workload_index_recs(timestamptz: timestamptz) → string

Returns set of index recommendations

+		Immutable
+ +### Spatial functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
_st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
geometrytype(geometry: geometry) → string

Returns the type of geometry as a string.

+

This function utilizes the GEOS module.

+		Immutable
geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
postgis_addbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_dropbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_extensions_upgrade() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_full_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_geos_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_getbbox(geometry: geometry) → box2d

Returns a box2d encapsulating the given Geometry.

+		Immutable
postgis_hasbbox(geometry: geometry) → bool

Returns whether a given Geometry has a bounding box. False for points and empty geometries; always true otherwise.

+		Immutable
postgis_lib_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_lib_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_liblwgeom_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_libxml_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_proj_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_installed() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_released() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_wagyu_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
st_addmeasure(geometry: geometry, start: float, end: float) → geometry

Returns a copy of a LineString or MultiLineString with measure coordinates linearly interpolated between the specified start and end values. Any existing M coordinates will be overwritten.

+		Immutable
st_addpoint(line_string: geometry, point: geometry) → geometry

Adds a Point to the end of a LineString.

+		Immutable
st_addpoint(line_string: geometry, point: geometry, index: int) → geometry

Adds a Point to a LineString at the given 0-based index (-1 to append).

+		Immutable
st_affine(geometry: geometry, a: float, b: float, c: float, d: float, e: float, f: float, g: float, h: float, i: float, x_off: float, y_off: float, z_off: float) → geometry

Applies a 3D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b c x_off \ / x
+| d e f y_off | | y | +| g h i z_off | | z | +\ 0 0 0 1 / \ 0 /

+		Immutable
st_affine(geometry: geometry, a: float, b: float, d: float, e: float, x_off: float, y_off: float) → geometry

Applies a 2D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b x_off \ / x
+| d e y_off | | y | +\ 0 0 1 / \ 0 /

+		Immutable
st_angle(line1: geometry, line2: geometry) → float

Returns the clockwise angle between two LINESTRING geometries, treating them as vectors between their start- and endpoints. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry) → float

Returns the clockwise angle between the vectors formed by point2,point1 and point2,point3. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry, point4: geometry) → float

Returns the clockwise angle between the vectors formed by point1,point2 and point3,point4. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_area(geography: geography) → float

Returns the area of the given geography in meters^2. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geography: geography, use_spheroid: bool) → float

Returns the area of the given geography in meters^2.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_area(geometry_str: string) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_area2d(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_asbinary(geography: geography) → bytes

Returns the WKB representation of a given Geography.

+		Immutable
st_asbinary(geography: geography, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asbinary(geometry: geometry) → bytes

Returns the WKB representation of a given Geometry.

+		Immutable
st_asbinary(geometry: geometry, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asencodedpolyline(geometry: geometry) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Preserves 5 decimal places.

+		Immutable
st_asencodedpolyline(geometry: geometry, precision: int4) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+		Immutable
st_asewkb(geography: geography) → bytes

Returns the EWKB representation of a given Geography.

+		Immutable
st_asewkb(geometry: geometry) → bytes

Returns the EWKB representation of a given Geometry.

+		Immutable
st_asewkt(geography: geography) → string

Returns the EWKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_asewkt(geography: geography, max_decimal_digits: int) → string

Returns the EWKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry: geometry) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_asewkt(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry_str: string) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asewkt(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geography: geography) → string

Returns the GeoJSON representation of a given Geography. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option (default for Geography)
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326
    • +
+		Immutable
st_asgeojson(geometry: geometry) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+		Immutable
st_asgeojson(geometry_str: string) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(row: tuple) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(row: tuple, geo_column: string) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. Coordinates have a maximum of 9 decimal digits.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int, pretty: bool) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value. Output will be pretty printed in JSON if pretty is true.

+		Stable
st_ashexewkb(geography: geography) → string

Returns the EWKB representation in hex of a given Geography.

+		Immutable
st_ashexewkb(geography: geography, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexewkb(geometry: geometry) → string

Returns the EWKB representation in hex of a given Geometry.

+		Immutable
st_ashexewkb(geometry: geometry, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexwkb(geography: geography) → string

Returns the WKB representation in hex of a given Geography.

+		Immutable
st_ashexwkb(geometry: geometry) → string

Returns the WKB representation in hex of a given Geometry.

+		Immutable
st_askml(geography: geography) → string

Returns the KML representation of a given Geography.

+		Immutable
st_askml(geometry: geometry) → string

Returns the KML representation of a given Geometry.

+		Immutable
st_askml(geometry_str: string) → string

Returns the KML representation of a given Geometry.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping. +Uses 4096 as the tile extent size in tile coordinate space.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int, clip: bool) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds if required.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry can be transformed, and clipped if required.

+		Immutable
st_astext(geography: geography) → string

Returns the WKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_astext(geography: geography, max_decimal_digits: int) → string

Returns the WKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry: geometry) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_astext(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry_str: string) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astext(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int, precision_m: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_azimuth(geography_a: geography, geography_b: geography) → float

Returns the azimuth in radians of the segment defined by the given point geographies, or NULL if the two points are coincident. It is solved using the Inverse geodesic problem.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_azimuth(geometry_a: geometry, geometry_b: geometry) → float

Returns the azimuth in radians of the segment defined by the given point geometries, or NULL if the two points are coincident.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+		Immutable
st_bdpolyfromtext(str: string, srid: int) → geometry

Returns a Polygon from multilinestring WKT with a SRID. If the input is not a multilinestring an error will be thrown.

+		Immutable
st_boundary(geometry: geometry) → geometry

Returns the closure of the combinatorial boundary of this Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_box2dfromgeohash(geohash: string) → box2d

Return a Box2D from a GeoHash string with max precision.

+		Immutable
st_box2dfromgeohash(geohash: string, precision: int) → box2d

Return a Box2D from a GeoHash string with supplied precision.

+		Immutable
st_buffer(geography: geography, distance: float) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, buffer_style_params: string) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, quad_segs: int) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geometry: geometry, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry_str: string, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_centroid(geography: geography) → geography

Returns the centroid of given geography. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geography: geography, use_spheroid: bool) → geography

Returns the centroid of given geography.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geometry: geometry) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_centroid(geometry_str: string) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_clipbybox2d(geometry: geometry, box2d: box2d) → geometry

Clips the geometry to conform to the bounding box specified by box2d.

+		Immutable
st_closestpoint(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the 2-dimensional point on geometry_a that is closest to geometry_b. This is the first point of the shortest line.

+		Immutable
st_collectionextract(geometry: geometry, type: int) → geometry

Given a collection, returns a multitype consisting only of elements of the specified type. If there are no elements of the given type, an EMPTY geometry is returned. Types are specified as 1=POINT, 2=LINESTRING, 3=POLYGON - other types are not supported.

+		Immutable
st_collectionhomogenize(geometry: geometry) → geometry

Returns the “simplest” representation of a collection’s contents. Collections of a single type will be returned as an appopriate multitype, or a singleton if it only contains a single geometry.

+		Immutable
st_combinebbox(box2d: box2d, geometry: geometry) → box2d

Combines the current bounding box with the bounding box of the Geometry.

+		Immutable
st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_convexhull(geometry: geometry) → geometry

Returns a geometry that represents the Convex Hull of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_coorddim(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_difference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the difference of two Geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_dimension(geometry: geometry) → int

Returns the number of topological dimensions of a given Geometry.

+		Immutable
st_disjoint(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a does not overlap, touch or is within geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_distance(geography_a: geography, geography_b: geography) → float

Returns the distance in meters between geography_a and geography_b. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geography_a: geography, geography_b: geography, use_spheroid: bool) → float

Returns the distance in meters between geography_a and geography_b.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance between the given geometries.

+		Immutable
st_distance(geometry_a_str: string, geometry_b_str: string) → float

Returns the distance between the given geometries.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_distancesphere(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_distancespheroid(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a spheroid.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_endpoint(geometry: geometry) → geometry

Returns the last point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_envelope(box2d: box2d) → geometry

Returns a bounding geometry for the given box.

+		Immutable
st_envelope(geometry: geometry) → geometry

Returns a bounding envelope for the given geometry.

+

For geometries which have a POINT or LINESTRING bounding box (i.e. is a single point +or a horizontal or vertical line), a POINT or LINESTRING is returned. Otherwise, the +returned POLYGON will be ordered Bottom Left, Top Left, Top Right, Bottom Right, +Bottom Left.

+		Immutable
st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string, parent_only: bool) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+

The parent_only boolean is always ignored.

+		Stable
st_estimatedextent(table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_expand(box2d: box2d, delta: float) → box2d

Extends the box2d by delta units across all dimensions.

+		Immutable
st_expand(box2d: box2d, delta_x: float, delta_y: float) → box2d

Extends the box2d by delta_x units in the x dimension and delta_y units in the y dimension.

+		Immutable
st_expand(geometry: geometry, delta: float) → geometry

Extends the bounding box represented by the geometry by delta units across all dimensions, returning a Polygon representing the new bounding box.

+		Immutable
st_expand(geometry: geometry, delta_x: float, delta_y: float) → geometry

Extends the bounding box represented by the geometry by delta_x units in the x dimension and delta_y units in the y dimension, returning a Polygon representing the new bounding box.

+		Immutable
st_exteriorring(geometry: geometry) → geometry

Returns the exterior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon.

+		Immutable
st_flipcoordinates(geometry: geometry) → geometry

Returns a new geometry with the X and Y axes flipped.

+		Immutable
st_force2d(geometry: geometry) → geometry

Returns a Geometry that is forced into XY layout with any Z or M dimensions discarded.

+		Immutable
st_force3d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to 0. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry, defaultM: float) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to the specified default M value. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force4d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZM layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float, defaultM: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified Z value. If a M coordinate doesn’t exist, it will be set to the specified M value.

+		Immutable
st_forcecollection(geometry: geometry) → geometry

Converts the geometry into a GeometryCollection.

+		Immutable
st_forcepolygonccw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_forcepolygoncw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Frechet distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Frechet distance between the given geometries, with the given segment densification (range 0.0-1.0, -1 to disable).

+

Smaller densify_frac gives a more accurate Fréchet distance. However, the computation time and memory usage increases with the square of the number of subsegments.

+

This function utilizes the GEOS module.

+		Immutable
st_generatepoints(geometry: geometry, npoints: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. Uses system time as a seed. +The requested number of points must be not larger than 65336.

+		Volatile
st_generatepoints(geometry: geometry, npoints: int4, seed: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. +The requested number of points must be not larger than 65336.

+		Immutable
st_geogfromewkb(val: bytes) → geography

Returns the Geography from an EWKB representation.

+		Immutable
st_geogfromewkt(val: string) → geography

Returns the Geography from an EWKT representation.

+		Immutable
st_geogfromgeojson(val: string) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromgeojson(val: jsonb) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geogfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geogfromwkb(bytes: bytes, srid: int) → geography

Returns the Geography from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geogfromwkb(val: bytes) → geography

Returns the Geography from a WKB (or EWKB) representation.

+		Immutable
st_geographyfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geographyfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geohash(geography: geography) → string

Returns a GeoHash representation of the geeographywith full precision if a point is provided, or with variable precision based on the size of the feature.

+		Immutable
st_geohash(geography: geography, precision: int) → string

Returns a GeoHash representation of the geography with the supplied precision.

+		Immutable
st_geohash(geometry: geometry) → string

Returns a GeoHash representation of the geometry with full precision if a point is provided, or with variable precision based on the size of the feature. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geohash(geometry: geometry, precision: int) → string

Returns a GeoHash representation of the geometry with the supplied precision. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geomcollfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomcollfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geometryfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geometryfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geometryn(geometry: geometry, n: int) → geometry

Returns the n-th Geometry (1-indexed). Returns NULL if out of bounds.

+		Immutable
st_geometrytype(geometry: geometry) → string

Returns the type of geometry as a string prefixed with ST_.

+

This function utilizes the GEOS module.

+		Immutable
st_geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
st_geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
st_geomfromgeohash(geohash: string) → geometry

Return a POLYGON Geometry from a GeoHash string with max precision.

+		Immutable
st_geomfromgeohash(geohash: string, precision: int) → geometry

Return a POLYGON Geometry from a GeoHash string with supplied precision.

+		Immutable
st_geomfromgeojson(val: string) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromgeojson(val: jsonb) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geomfromwkb(bytes: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geomfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_hasarc(geometry: geometry) → bool

Returns whether there is a CIRCULARSTRING in the geometry.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Hausdorff distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Hausdorff distance between the given geometries, with the given segment densification (range 0.0-1.0).

+

This function utilizes the GEOS module.

+		Immutable
st_interiorringn(geometry: geometry, n: int) → geometry

Returns the n-th (1-indexed) interior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon, or the ring does not exist.

+		Immutable
st_intersection(geography_a: geography, geography_b: geography) → geography

Returns the point intersections of the given geographies.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a_str: string, geometry_b_str: string) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_isclosed(geometry: geometry) → bool

Returns whether the geometry is closed as defined by whether the start and end points are coincident. Points are considered closed, empty geometries are not. For collections and multi-types, all members must be closed, as must all polygon rings.

+		Immutable
st_iscollection(geometry: geometry) → bool

Returns whether the geometry is of a collection type (including multi-types).

+		Immutable
st_isempty(geometry: geometry) → bool

Returns whether the geometry is empty.

+		Immutable
st_ispolygonccw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are considered counter-clockwise.

+		Immutable
st_ispolygoncw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are considered clockwise.

+		Immutable
st_isring(geometry: geometry) → bool

Returns whether the geometry is a single linestring that is closed and simple, as defined by ST_IsClosed and ST_IsSimple.

+

This function utilizes the GEOS module.

+		Immutable
st_issimple(geometry: geometry) → bool

Returns true if the geometry has no anomalous geometric points, e.g. that it intersects with or lies tangent to itself.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry) → bool

Returns whether the geometry is valid as defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry, flags: int) → bool

Returns whether the geometry is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry) → string

Returns a string containing the reason the geometry is invalid along with the point of interest, or “Valid Geometry” if it is valid. Validity is defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry, flags: int) → string

Returns the reason the geometry is invalid or “Valid Geometry” if it is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidtrajectory(geometry: geometry) → bool

Returns whether the geometry encodes a valid trajectory.

+

Note the geometry must be a LineString with M coordinates.

+		Immutable
st_length(geography: geography) → float

Returns the length of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geography: geography, use_spheroid: bool) → float

Returns the length of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_length(geometry_str: string) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_length2d(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_linecrossingdirection(linestring_a: geometry, linestring_b: geometry) → int

Returns an interger value defining behavior of crossing of lines: +0: lines do not cross, +-1: linestring_b crosses linestring_a from right to left, +1: linestring_b crosses linestring_a from left to right, +-2: linestring_b crosses linestring_a multiple times from right to left, +2: linestring_b crosses linestring_a multiple times from left to right, +-3: linestring_b crosses linestring_a multiple times from left to left, +3: linestring_b crosses linestring_a multiple times from right to right.

+

Note that the top vertex of the segment touching another line does not count as a crossing, but the bottom vertex of segment touching another line is considered a crossing.

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string) → geometry

Creates a LineString from an Encoded Polyline string.

+

Returns valid results only if the polyline was encoded with 5 decimal places.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string, precision: int4) → geometry

Creates a LineString from an Encoded Polyline string.

+

Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefrommultipoint(geometry: geometry) → geometry

Creates a LineString from a MultiPoint geometry.

+		Immutable
st_linefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_lineinterpolatepoint(geometry: geometry, fraction: float) → geometry

Returns a point along the given LineString which is at given fraction of LineString’s total length.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float, repeat: bool) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length. If repeat is false (default true) then it returns first point.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_linelocatepoint(line: geometry, point: geometry) → float

Returns a float between 0 and 1 representing the location of the closest point on LineString to the given Point, as a fraction of total 2d line length.

+		Immutable
st_linemerge(geometry: geometry) → geometry

Returns a LineString or MultiLineString by joining together constituents of a MultiLineString with matching endpoints. If the input is not a MultiLineString or LineString, an empty GeometryCollection is returned.

+

This function utilizes the GEOS module.

+		Immutable
st_linestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: decimal, end_fraction: decimal) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: float, end_fraction: float) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_longestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the max distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the maximum distance between the geometry’s vertexes. The function will return the longest line that was discovered first when comparing maximum distances if more than one is found.

+		Immutable
st_m(geometry: geometry) → float

Returns the M coordinate of a geometry if it is a Point.

+		Immutable
st_makebox2d(geometry_a: geometry, geometry_b: geometry) → box2d

Creates a box2d from two points. Errors if arguments are not two non-empty points.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with SRID 0.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float, srid: int) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with the given SRID.

+		Immutable
st_makepoint(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float) → geometry

Returns a new Point with the given X, Y, and Z coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float, m: float) → geometry

Returns a new Point with the given X, Y, Z, and M coordinates.

+		Immutable
st_makepointm(x: float, y: float, m: float) → geometry

Returns a new Point with the given X, Y, and M coordinates.

+		Immutable
st_makepolygon(geometry: geometry) → geometry

Returns a new Polygon with the given outer LineString.

+		Immutable
st_makepolygon(outer: geometry, interior: anyelement[]) → geometry

Returns a new Polygon with the given outer LineString and interior (hole) LineString(s).

+		Immutable
st_makevalid(geometry: geometry) → geometry

Returns a valid form of the given geometry according to the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_maxdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the maximum distance across every pair of points comprising the given geometries. Note if the geometries are the same, it will return the maximum distance between the geometry’s vertexes.

+		Immutable
st_memsize(geometry: geometry) → int

Returns the amount of memory space (in bytes) the geometry takes.

+		Immutable
st_minimumboundingcircle(geometry: geometry) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingcircle(geometry: geometry, num_segs: int) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingradius(geometry: geometry) → tuple{geometry AS center, float AS radius}

Returns a record containing the center point and radius of the smallest circle that can fully contains the given geometry.

+		Immutable
st_minimumclearance(geometry: geometry) → float

Returns the minimum distance a vertex can move before producing an invalid geometry. Returns Infinity if no minimum clearance can be found (e.g. for a single point).

+		Immutable
st_minimumclearanceline(geometry: geometry) → geometry

Returns a LINESTRING spanning the minimum distance a vertex can move before producing an invalid geometry. If no minimum clearance can be found (e.g. for a single point), an empty LINESTRING is returned.

+		Immutable
st_mlinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mlinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mpointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multi(geometry: geometry) → geometry

Returns the geometry as a new multi-geometry, e.g converts a POINT to a MULTIPOINT. If the input is already a multitype or collection, it is returned as is.

+		Immutable
st_multilinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multipointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_ndims(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_node(geometry: geometry) → geometry

Adds a node on a geometry for each intersection. Resulting geometry is always a MultiLineString.

+		Immutable
st_normalize(geometry: geometry) → geometry

Returns the geometry in its normalized form.

+

This function utilizes the GEOS module.

+		Immutable
st_npoints(geometry: geometry) → int

Returns the number of points in a given Geometry. Works for any shape type.

+		Immutable
st_nrings(geometry: geometry) → int

Returns the number of rings in a Polygon Geometry. Returns 0 if the shape is not a Polygon.

+		Immutable
st_numgeometries(geometry: geometry) → int

Returns the number of shapes inside a given Geometry.

+		Immutable
st_numinteriorring(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numinteriorrings(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numpoints(geometry: geometry) → int

Returns the number of points in a LineString. Returns NULL if the Geometry is not a LineString.

+		Immutable
st_orderingequals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is exactly equal to geometry_b, having all coordinates in the same order, as well as the same type, SRID, bounding box, and so on.

+		Immutable
st_orientedenvelope(geometry: geometry) → geometry

Returns a minimum rotated rectangle enclosing a geometry. +Note that more than one minimum rotated rectangle may exist. +May return a Point or LineString in the case of degenerate inputs.

+		Immutable
st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_perimeter(geography: geography) → float

Returns the perimeter of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geography: geography, use_spheroid: bool) → float

Returns the perimeter of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_perimeter2d(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_point(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_pointfromgeohash(geohash: string) → geometry

Return a POINT Geometry from a GeoHash string with max precision.

+		Immutable
st_pointfromgeohash(geohash: string, precision: int) → geometry

Return a POINT Geometry from a GeoHash string with supplied precision.

+		Immutable
st_pointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Point, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_pointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointinsidecircle(geometry: geometry, x_coord: float, y_coord: float, radius: float) → bool

Returns the true if the geometry is a point and is inside the circle. Returns false otherwise.

+		Immutable
st_pointn(geometry: geometry, n: int) → geometry

Returns the n-th Point of a LineString (1-indexed). Returns NULL if out of bounds or not a LineString.

+		Immutable
st_pointonsurface(geometry: geometry) → geometry

Returns a point that intersects with the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_points(geometry: geometry) → geometry

Returns all coordinates in the given Geometry as a MultiPoint, including duplicates.

+		Immutable
st_polyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygon(geometry: geometry, srid: int) → geometry

Returns a new Polygon from the given LineString and sets its SRID. It is equivalent to ST_MakePolygon with a single argument followed by ST_SetSRID.

+		Immutable
st_polygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_project(geography: geography, distance: float, azimuth: float) → geography

Returns a point projected from a start point along a geodesic using a given distance and azimuth (bearing). +This is known as the direct geodesic problem.

+

The distance is given in meters. Negative values are supported.

+

The azimuth (also known as heading or bearing) is given in radians. It is measured clockwise from true north (azimuth zero). +East is azimuth π/2 (90 degrees); south is azimuth π (180 degrees); west is azimuth 3π/2 (270 degrees). +Negative azimuth values and values greater than 2π (360 degrees) are supported.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, bnr: int) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b using the given boundary node rule (1:OGC/MOD2, 2:Endpoint, 3:MultivalentEndpoint, 4:MonovalentEndpoint).

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, pattern: string) → bool

Returns whether the DE-9IM spatial relation between geometry_a and geometry_b matches the DE-9IM pattern.

+

This function utilizes the GEOS module.

+		Immutable
st_relatematch(intersection_matrix: string, pattern: string) → bool

Returns whether the given DE-9IM intersection matrix satisfies the given pattern.

+		Immutable
st_removepoint(line_string: geometry, index: int) → geometry

Removes the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_removerepeatedpoints(geometry: geometry) → geometry

Returns a geometry with repeated points removed.

+		Immutable
st_removerepeatedpoints(geometry: geometry, tolerance: float) → geometry

Returns a geometry with repeated points removed, within the given distance tolerance.

+		Immutable
st_reverse(geometry: geometry) → geometry

Returns a modified geometry by reversing the order of its vertices.

+		Immutable
st_rotate(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_point: geometry) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_x: float, origin_y: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotatex(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the x axis by a rotation angle.

+		Immutable
st_rotatey(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the y axis by a rotation angle.

+		Immutable
st_rotatez(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the z axis by a rotation angle.

+		Immutable
st_s2covering(geography: geography) → geography

Returns a geography which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geography: geography, settings: string) → geography

Returns a geography which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geography, 's2_max_level=15,s2_level_mod=3').

+		Immutable
st_s2covering(geometry: geometry) → geometry

Returns a geometry which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geometry: geometry, settings: string) → geometry

Returns a geometry which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geometry, 's2_max_level=15,s2_level_mod=3')

+		Immutable
st_scale(g: geometry, factor: geometry) → geometry

Returns a modified Geometry scaled by taking in a Geometry as the factor.

+		Immutable
st_scale(g: geometry, factor: geometry, origin: geometry) → geometry

Returns a modified Geometry scaled by the Geometry factor relative to a false origin.

+		Immutable
st_scale(geometry: geometry, x_factor: float, y_factor: float) → geometry

Returns a modified Geometry scaled by the given factors.

+		Immutable
st_segmentize(geography: geography, max_segment_length_meters: float) → geography

Returns a modified Geography having no segment longer than the given max_segment_length meters.

+

The calculations are done on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_segmentize(geometry: geometry, max_segment_length: float) → geometry

Returns a modified Geometry having no segment longer than the given max_segment_length. Length units are in units of spatial reference.

+		Immutable
st_setpoint(line_string: geometry, index: int, point: geometry) → geometry

Sets the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_setsrid(geography: geography, srid: int) → geography

Sets a Geography to a new SRID without transforming the coordinates.

+		Immutable
st_setsrid(geometry: geometry, srid: int) → geometry

Sets a Geometry to a new SRID without transforming the coordinates.

+		Immutable
st_sharedpaths(geometry_a: geometry, geometry_b: geometry) → geometry

Returns a collection containing paths shared by the two input geometries.

+

Those going in the same direction are in the first element of the collection, +those going in the opposite direction are in the second element. +The paths themselves are given in the direction of the first geometry.

+		Immutable
st_shiftlongitude(geometry: geometry) → geometry

Returns a modified version of a geometry in which the longitude (X coordinate) of each point is incremented by 360 if it is <0 and decremented by 360 if it is >180. The result is only meaningful if the coordinates are in longitude/latitude.

+		Immutable
st_shortestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the minimum distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the minimum distance between the geometry’s vertexes. The function will return the shortest line that was discovered first when comparing minimum distances if more than one is found.

+		Immutable
st_simplify(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm.

+

This function utilizes the GEOS module.

+		Immutable
st_simplify(geometry: geometry, tolerance: float, preserve_collapsed: bool) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, retaining objects that would be too small given the tolerance if preserve_collapsed is set to true.

+		Immutable
st_simplifypreservetopology(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, avoiding the creation of invalid geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_snap(input: geometry, target: geometry, tolerance: float) → geometry

Snaps the vertices and segments of input geometry the target geometry’s vertices. +Tolerance is used to control where snapping is performed. The result geometry is the input geometry with the vertices snapped. +If no snapping occurs then the input geometry is returned unchanged.

+		Immutable
st_snaptogrid(geometry: geometry, origin: geometry, size_x: float, size_y: float, size_z: float, size_m: float) → geometry

Snap a geometry to a grid defined by the given origin and X, Y, Z, and M cell sizes. Any dimension with a 0 cell size will not be snapped.

+		Immutable
st_snaptogrid(geometry: geometry, origin_x: float, origin_y: float, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y based on an origin of (origin_x, origin_y).

+		Immutable
st_snaptogrid(geometry: geometry, size: float) → geometry

Snap a geometry to a grid of the given size. The specified size is only used to snap X and Y coordinates.

+		Immutable
st_snaptogrid(geometry: geometry, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y.

+		Immutable
st_srid(geography: geography) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geography as defined in spatial_ref_sys table.

+		Immutable
st_srid(geometry: geometry) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geometry as defined in spatial_ref_sys table.

+		Immutable
st_startpoint(geometry: geometry) → geometry

Returns the first point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_subdivide(geometry: geometry) → geometry

Returns a geometry divided into parts, where each part contains no more than 256 vertices.

+		Immutable
st_subdivide(geometry: geometry, max_vertices: int4) → geometry

Returns a geometry divided into parts, where each part contains no more than the number of vertices provided.

+		Immutable
st_summary(geography: geography) → string

Returns a text summary of the contents of the geography.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_summary(geometry: geometry) → string

Returns a text summary of the contents of the geometry.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_swapordinates(geometry: geometry, swap_ordinate_string: string) → geometry

Returns a version of the given geometry with given ordinates swapped. +The swap_ordinate_string parameter is a 2-character string naming the ordinates to swap. Valid names are: x, y, z and m.

+		Immutable
st_symdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_symmetricdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4, bounds: geometry) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4, bounds: geometry, margin: float) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, srid: int) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates. The supplied SRID is set on the new geometry.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, srid: int) → geometry

Transforms a geometry into the given SRID coordinate reference system by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system referenced by the projection text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float, delta_z: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_transscale(geometry: geometry, delta_x: float, delta_y: float, x_factor: float, y_factor: float) → geometry

Translates the geometry using the deltaX and deltaY args, then scales it using the XFactor, YFactor args, working in 2D only.

+		Immutable
st_unaryunion(geometry: geometry) → geometry

Returns a union of the components for any geometry or geometry collection provided. Dissolves boundaries of a multipolygon.

+		Immutable
st_voronoilines(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoipolygons(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_wkbtosql(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_wkttosql(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_x(geometry: geometry) → float

Returns the X coordinate of a geometry if it is a Point.

+		Immutable
st_xmax(box2d: box2d) → float

Returns the maximum X ordinate of a box2d.

+		Immutable
st_xmax(geometry: geometry) → float

Returns the maximum X ordinate of a geometry.

+		Immutable
st_xmin(box2d: box2d) → float

Returns the minimum X ordinate of a box2d.

+		Immutable
st_xmin(geometry: geometry) → float

Returns the minimum X ordinate of a geometry.

+		Immutable
st_y(geometry: geometry) → float

Returns the Y coordinate of a geometry if it is a Point.

+		Immutable
st_ymax(box2d: box2d) → float

Returns the maximum Y ordinate of a box2d.

+		Immutable
st_ymax(geometry: geometry) → float

Returns the maximum Y ordinate of a geometry.

+		Immutable
st_ymin(box2d: box2d) → float

Returns the minimum Y ordinate of a box2d.

+		Immutable
st_ymin(geometry: geometry) → float

Returns the minimum Y ordinate of a geometry.

+		Immutable
st_z(geometry: geometry) → float

Returns the Z coordinate of a geometry if it is a Point.

+		Immutable
st_zmflag(geometry: geometry) → int2

Returns a code based on the ZM coordinate dimension of a geometry (XY = 0, XYM = 1, XYZ = 2, XYZM = 3).

+		Immutable
+ +### String and byte functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ascii(val: string) → int

Returns the character code of the first character in val. Despite the name, the function supports Unicode too.

+		Immutable
bit_count(val: bytes) → int

Calculates the number of bits set used to represent val.

+		Immutable
bit_count(val: varbit) → int

Calculates the number of bits set used to represent val.

+		Immutable
bit_length(val: bytes) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: string) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
bitmask_and(a: string, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: string, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
btrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning or end of input (applies recursively).

+

For example, btrim('doggie', 'eod') returns ggi.

+		Immutable
btrim(val: string) → string

Removes all spaces from the beginning and end of val.

+		Immutable
char_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
char_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
character_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
character_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
chr(val: int) → string

Returns the character with the code given in val. Inverse function of ascii().

+		Immutable
compress(data: bytes, codec: string) → bytes

Compress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
concat(anyelement...) → string

Concatenates a comma-separated list of strings.

+		Immutable
concat_ws(string...) → string

Uses the first argument as a separator between the concatenation of the subsequent arguments.

+

For example concat_ws('!','wow','great') returns wow!great.

+		Immutable
convert_from(str: bytes, enc: string) → string

Decode the bytes in str into a string using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
convert_to(str: string, enc: string) → bytes

Encode the string str as a byte array using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
decode(text: string, format: string) → bytes

Decodes data using format (hex / escape / base64).

+		Immutable
decompress(data: bytes, codec: string) → bytes

Decompress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
difference(source: string, target: string) → int

Convert two strings to their Soundex codes and report the number of matching code positions.

+		Immutable
encode(data: bytes, format: string) → string

Encodes data using format (hex / escape / base64).

+		Immutable
format(string, anyelement...) → string

Interprets the first argument as a format string similar to C sprintf and interpolates the remaining arguments.

+		Stable
from_ip(val: bytes) → string

Converts the byte string representation of an IP to its character string representation.

+		Immutable
from_uuid(val: bytes) → string

Converts the byte string representation of a UUID to its character string representation.

+		Immutable
get_bit(bit_string: varbit, index: int) → int

Extracts a bit at given index in the bit array.

+		Immutable
get_bit(byte_string: bytes, index: int) → int

Extracts a bit at the given index in the byte array.

+		Immutable
get_byte(byte_string: bytes, index: int) → int

Extracts a byte at the given index in the byte array.

+		Immutable
initcap(val: string) → string

Capitalizes the first letter of val.

+		Immutable
left(input: bytes, return_set: int) → bytes

Returns the first return_set bytes from input.

+		Immutable
left(input: string, return_set: int) → string

Returns the first return_set characters from input.

+		Immutable
length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
length(val: string) → int

Calculates the number of characters in val.

+		Immutable
length(val: varbit) → int

Calculates the number of bits in val.

+		Immutable
lower(val: string) → string

Converts all characters in val to their lower-case equivalents.

+		Immutable
lpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the left of string.If string is longer than length it is truncated.

+		Immutable
lpad(string: string, length: int, fill: string) → string

Pads string by adding fill to the left of string to make it length. If string is longer than length it is truncated.

+		Immutable
ltrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning (left-hand side) of input (applies recursively).

+

For example, ltrim('doggie', 'od') returns ggie.

+		Immutable
ltrim(val: string) → string

Removes all spaces from the beginning (left-hand side) of val.

+		Immutable
md5(bytes...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
md5(string...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
octet_length(val: bytes) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: string) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int) → string

Replaces characters in input with overlay_val starting at start_pos (begins at 1).

+

For example, overlay('doggie', 'CAT', 2) returns dCATie.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int, end_pos: int) → string

Deletes the characters in input between start_pos and end_pos (count starts at 1), and then insert overlay_val at start_pos.

+		Immutable
parse_date(string: string, datestyle: string) → date

Parses a date assuming it is in format specified by DateStyle.

+		Immutable
parse_date(val: string) → date

Parses a date assuming it is in MDY format.

+		Immutable
parse_ident(qualified_identifier: string) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. Extra characters after the last identifier are considered an error

+		Immutable
parse_ident(qualified_identifier: string, strict: bool) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. If strict is false, then extra characters after the last identifier are ignored.

+		Immutable
parse_interval(string: string, style: string) → interval

Convert a string to an interval using the given IntervalStyle.

+		Immutable
parse_interval(val: string) → interval

Convert a string to an interval assuming the Postgres IntervalStyle.

+		Immutable
parse_time(string: string, timestyle: string) → time

Parses a time assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_time(val: string) → time

Parses a time assuming the date (if any) is in MDY format.

+		Immutable
parse_timestamp(string: string, datestyle: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates formatted using the given DateStyle.

+		Immutable
parse_timestamp(val: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates are in MDY format.

+		Immutable
parse_timetz(string: string, timestyle: string) → timetz

Parses a timetz assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_timetz(val: string) → timetz

Parses a timetz assuming the date (if any) is in MDY format.

+		Immutable
prettify_statement(statement: string, line_width: int, align_mode: int, case_mode: int) → string

Prettifies a statement using a user-configured pretty-printing config. +Align mode values range from 0 - 3, representing no, partial, full, and extra alignment respectively. +Case mode values range between 0 - 1, representing lower casing and upper casing respectively.

+		Immutable
prettify_statement(val: string) → string

Prettifies a statement using a the default pretty-printing config.

+		Immutable
quote_ident(val: string) → string

Return val suitably quoted to serve as identifier in a SQL statement.

+		Immutable
quote_literal(val: string) → string

Return val suitably quoted to serve as string literal in a SQL statement.

+		Immutable
quote_literal(val: anyelement) → string

Coerce val to a string and then quote it as a literal.

+		Stable
quote_nullable(val: string) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Immutable
quote_nullable(val: anyelement) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Stable
regexp_extract(input: string, regex: string) → string

Returns the first match for the Regular Expression regex in input.

+		Immutable
regexp_replace(input: string, regex: string, replace: string) → string

Replaces matches for the Regular Expression regex in input with the Regular Expression replace.

+		Immutable
regexp_replace(input: string, regex: string, replace: string, flags: string) → string

Replaces matches for the regular expression regex in input with the regular expression replace using flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
repeat(input: string, repeat_counter: int) → string

Concatenates input repeat_counter number of times.

+

For example, repeat('dog', 2) returns dogdog.

+		Immutable
replace(input: string, find: string, replace: string) → string

Replaces all occurrences of find with replace in input

+		Immutable
reverse(val: string) → string

Reverses the order of the string’s characters.

+		Immutable
right(input: bytes, return_set: int) → bytes

Returns the last return_set bytes from input.

+		Immutable
right(input: string, return_set: int) → string

Returns the last return_set characters from input.

+		Immutable
rpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the right of string. If string is longer than length it is truncated.

+		Immutable
rpad(string: string, length: int, fill: string) → string

Pads string to length by adding fill to the right of string. If string is longer than length it is truncated.

+		Immutable
rtrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the end (right-hand side) of input (applies recursively).

+

For example, rtrim('doggie', 'ei') returns dogg.

+		Immutable
rtrim(val: string) → string

Removes all spaces from the end (right-hand side) of val.

+		Immutable
set_bit(bit_string: varbit, index: int, to_set: int) → varbit

Updates a bit at given index in the bit array.

+		Immutable
set_bit(byte_string: bytes, index: int, to_set: int) → bytes

Updates a bit at the given index in the byte array.

+		Immutable
set_byte(byte_string: bytes, index: int, to_set: int) → bytes

Updates a byte at the given index in the byte array.

+		Immutable
sha1(bytes...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha1(string...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha224(bytes...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha224(string...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha256(bytes...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha256(string...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha384(bytes...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha384(string...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha512(bytes...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
sha512(string...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
similar_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_to_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
split_part(input: string, delimiter: string, return_index_pos: int) → string

Splits input on delimiter and return the value in the return_index_pos position (starting at 1).

+

For example, split_part('123.456.789.0','.',3)returns 789.

+		Immutable
strpos(input: bytes, find: bytes) → int

Calculates the position where the byte subarray find begins in input.

+		Immutable
strpos(input: string, find: string) → int

Calculates the position where the string find begins in input.

+

For example, strpos('doggie', 'gie') returns 4.

+		Immutable
strpos(input: varbit, find: varbit) → int

Calculates the position where the bit subarray find begins in input.

+		Immutable
substr(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substr(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substr(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substring(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substring(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
to_char_with_style(date: date, datestyle: string) → string

Convert an date to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_char_with_style(interval: interval, style: string) → string

Convert an interval to a string using the given IntervalStyle.

+		Immutable
to_char_with_style(timestamp: timestamp, datestyle: string) → string

Convert an timestamp to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_english(val: int) → string

This function enunciates the value of its argument using English cardinals.

+		Immutable
to_hex(val: bytes) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: int) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: string) → string

Converts val to its hexadecimal representation.

+		Immutable
to_ip(val: string) → bytes

Converts the character string representation of an IP to its byte string representation.

+		Immutable
to_uuid(val: string) → bytes

Converts the character string representation of a UUID to its byte string representation.

+		Immutable
translate(input: string, find: string, replace: string) → string

In input, replaces the first character from find with the first character in replace; repeat for each character in find.

+

For example, translate('doggie', 'dog', '123'); returns 1233ie.

+		Immutable
ulid_to_uuid(val: string) → uuid

Converts a ULID string to its UUID-encoded representation.

+		Immutable
unaccent(val: string) → string

Removes accents (diacritic signs) from the text provided in val.

+		Immutable
upper(val: string) → string

Converts all characters in val to their to their upper-case equivalents.

+		Immutable
+ +### System info functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cluster_logical_timestamp() → decimal

Returns the logical time of the current transaction as +a CockroachDB HLC in decimal form.

+

Note that uses of this function disable server-side optimizations and +may increase either contention or retry errors, or both.

+

Returns an error if run in a transaction with an isolation level weaker than SERIALIZABLE.

+		Volatile
current_database() → string

Returns the current database.

+		Stable
current_schema() → string

Returns the current schema.

+		Stable
current_schemas(include_pg_catalog: bool) → string[]

Returns the valid schemas in the search path.

+		Stable
current_user() → string

Returns the current user. This function is provided for compatibility with PostgreSQL.

+		Stable
session_user() → string

Returns the session user. This function is provided for compatibility with PostgreSQL.

+		Stable
to_regclass(text: string) → regtype

Translates a textual relation name to its OID

+		Stable
to_regnamespace(text: string) → regtype

Translates a textual schema name to its OID

+		Stable
to_regproc(text: string) → regtype

Translates a textual function or procedure name to its OID

+		Stable
to_regprocedure(text: string) → regtype

Translates a textual function or procedure name(with argument types) to its OID

+		Stable
to_regrole(text: string) → regtype

Translates a textual role name to its OID

+		Stable
to_regtype(text: string) → regtype

Translates a textual type name to its OID

+		Stable
version() → string

Returns the node’s version of CockroachDB.

+		Volatile
+ +### TIMETZ functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
current_time() → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time() → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_time(precision: int) → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time(precision: int) → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → timetz

Returns the current transaction’s time with time zone.

+		Stable
localtime(precision: int) → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime(precision: int) → timetz

Returns the current transaction’s time with time zone.

+		Stable
+ +### Trigrams functions + + + + + + +
Function → ReturnsDescriptionVolatility
show_trgm(input: string) → string[]

Returns an array of all the trigrams in the given string.

+		Immutable
similarity(left: string, right: string) → float

Returns a number that indicates how similar the two arguments are. The range of the result is zero (indicating that the two strings are completely dissimilar) to one (indicating that the two strings are identical).

+		Immutable
+ +### UUID functions + + + + + +
Function → ReturnsDescriptionVolatility
uuid_to_ulid(val: uuid) → string

Converts a UUID-encoded ULID to its string representation.

+		Immutable
+ +### Compatibility functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
col_description(table_oid: oid, column_number: int) → string

Returns the comment for a table column, which is specified by the OID of its table and its column number. (obj_description cannot be used for table columns, since columns do not have OIDs of their own.)

+		Stable
current_setting(setting_name: string) → string

System info

+		Stable
current_setting(setting_name: string, missing_ok: bool) → string

System info

+		Stable
format_type(type_oid: oid, typemod: int) → string

Returns the SQL name of a data type that is identified by its type OID and possibly a type modifier. Currently, the type modifier is ignored.

+		Stable
getdatabaseencoding() → string

Returns the current encoding name used by the database.

+		Stable
has_any_column_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_column_privilege(table: string, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: string, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_database_privilege(database: string, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(database: oid, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(user: string, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: string, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_foreign_data_wrapper_privilege(fdw: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(fdw: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_function_privilege(function: string, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(function: oid, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(user: string, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: string, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_language_privilege(language: string, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(language: oid, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(user: string, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: string, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_schema_privilege(schema: string, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(schema: oid, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_sequence_privilege(sequence: string, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(sequence: oid, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_server_privilege(server: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(server: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_table_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_tablespace_privilege(tablespace: string, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(tablespace: oid, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_type_privilege(type: string, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(type: oid, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(user: string, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: string, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
information_schema._pg_numeric_precision(typid: oid, typmod: int4) → int

Returns the precision of the given type with type modifier

+		Immutable
information_schema._pg_numeric_precision_radix(typid: oid, typmod: int4) → int

Returns the radix of the given type with type modifier

+		Immutable
information_schema._pg_numeric_scale(typid: oid, typmod: int4) → int

Returns the scale of the given type with type modifier

+		Immutable
nameconcatoid(name: string, oid: oid) → name

Used in the information_schema to produce specific_name columns, which are supposed to be unique per schema. The result is the same as ($1::text || ‘_’ || $2::text)::name except that, if it would not fit in 63 characters, we make it do so by truncating the name input (not the oid).

+		Immutable
obj_description(object_oid: oid) → string

Returns the comment for a database object specified by its OID alone. This is deprecated since there is no guarantee that OIDs are unique across different system catalogs; therefore, the wrong comment might be returned.

+		Stable
obj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a database object specified by its OID and the name of the containing system catalog. For example, obj_description(123456, ‘pg_class’) would retrieve the comment for the table with OID 123456.

+		Stable
oidvectortypes(vector: oidvector) → string

Generates a comma seperated string of type names from an oidvector.

+		Stable
pg_backend_pid() → int

Returns a numerical ID attached to this session. This ID is part of the query cancellation key used by the wire protocol. This function was only added for compatibility, and unlike in Postgres, the returned value does not correspond to a real process ID.

+		Stable
pg_collation_for(str: anyelement) → string

Returns the collation of the argument

+		Stable
pg_column_is_updatable(reloid: oid, attnum: int2, include_triggers: bool) → bool

Returns whether the given column can be updated.

+		Stable
pg_column_size(anyelement...) → int

Return size in bytes of the column provided as an argument

+		Immutable
pg_function_is_visible(oid: oid) → bool

Returns whether the function with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_get_function_arg_default(func_oid: oid, arg_num: int4) → string

Get textual representation of a function argument’s default value. The second argument of this function is the argument number among all arguments (i.e. proallargtypes, not proargtypes), starting with 1, because that’s how information_schema.sql uses it. Currently, this always returns NULL, since CockroachDB does not support default values.

+		Stable
pg_get_function_arguments(func_oid: oid) → string

Returns the argument list (with defaults) necessary to identify a function, in the form it would need to appear in within CREATE FUNCTION.

+		Stable
pg_get_function_identity_arguments(func_oid: oid) → string

Returns the argument list (without defaults) necessary to identify a function, in the form it would need to appear in within ALTER FUNCTION, for instance.

+		Stable
pg_get_function_result(func_oid: oid) → string

Returns the types of the result of the specified function.

+		Stable
pg_get_functiondef(func_oid: oid) → string

For user-defined functions, returns the definition of the specified function. For builtin functions, returns the name of the function.

+		Stable
pg_get_indexdef(index_oid: oid) → string

Gets the CREATE INDEX command for index

+		Stable
pg_get_indexdef(index_oid: oid, column_no: int, pretty_bool: bool) → string

Gets the CREATE INDEX command for index, or definition of just one index column when given a non-zero column number

+		Stable
pg_get_serial_sequence(table_name: string, column_name: string) → string

Returns the name of the sequence used by the given column_name in the table table_name.

+		Stable
pg_get_viewdef(view_oid: oid) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_get_viewdef(view_oid: oid, pretty_bool: bool) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_has_role(role: string, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(role: oid, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(user: string, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: string, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_is_other_temp_schema(oid: oid) → bool

Returns true if the given OID is the OID of another session’s temporary schema. (This can be useful, for example, to exclude other sessions’ temporary tables from a catalog display.)

+		Stable
pg_my_temp_schema() → oid

Returns the OID of the current session’s temporary schema, or zero if it has none (because it has not created any temporary tables).

+		Stable
pg_relation_is_updatable(reloid: oid, include_triggers: bool) → int4

Returns the update events the relation supports.

+		Stable
pg_sequence_last_value(sequence_oid: oid) → int

Returns the last value generated by a sequence, or NULL if the sequence has not been used yet.

+		Volatile
pg_sleep(seconds: float) → bool

pg_sleep makes the current session’s process sleep until seconds seconds have elapsed. seconds is a value of type double precision, so fractional-second delays can be specified.

+		Volatile
pg_table_is_visible(oid: oid) → bool

Returns whether the table with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_type_is_visible(oid: oid) → bool

Returns whether the type with the given OID belongs to one of the schemas on the search path.

+		Stable
set_config(setting_name: string, new_value: string, is_local: bool) → string

System info

+		Volatile
shobj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a shared database object specified by its OID and the name of the containing system catalog. This is just like obj_description except that it is used for retrieving comments on shared objects (e.g. databases).

+		Stable
+ diff --git a/src/current/_includes/cockroach-generated/release-25.1/sql/operators.md b/src/current/_includes/cockroach-generated/release-25.1/sql/operators.md new file mode 100644 index 00000000000..73e12287102 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.1/sql/operators.md @@ -0,0 +1,662 @@ + + + + + +
#Return
int # intint
varbit # varbitvarbit
+ + + + +
#>Return
jsonb #> string[]jsonb
+ + + + +
#>>Return
jsonb #>> string[]string
+ + + + + + + + + +
%Return
decimal % decimaldecimal
decimal % intdecimal
float % floatfloat
int % decimaldecimal
int % intint
string % stringbool
+ + + + + + +
&Return
inet & inetinet
int & intint
varbit & varbitvarbit
+ + + + + + + + + +
&&Return
anyelement && anyelementbool
box2d && box2dbool
box2d && geometrybool
geometry && box2dbool
geometry && geometrybool
inet && inetbool
+ + + + + + + + + + + + + + + +
*Return
decimal * decimaldecimal
decimal * intdecimal
decimal * intervalinterval
float * floatfloat
float * intervalinterval
int * decimaldecimal
int * intint
int * intervalinterval
interval * decimalinterval
interval * floatinterval
interval * intinterval
vector * vectorvector
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Return
+decimaldecimal
+floatfloat
+intint
+intervalinterval
date + intdate
date + intervaltimestamp
date + timetimestamp
date + timetztimestamptz
decimal + decimaldecimal
decimal + intdecimal
decimal + pg_lsnpg_lsn
float + floatfloat
inet + intinet
int + datedate
int + decimaldecimal
int + inetinet
int + intint
interval + datetimestamp
interval + intervalinterval
interval + timetime
interval + timestamptimestamp
interval + timestamptztimestamptz
interval + timetztimetz
pg_lsn + decimalpg_lsn
time + datetimestamp
time + intervaltime
timestamp + intervaltimestamp
timestamptz + intervaltimestamptz
timetz + datetimestamptz
timetz + intervaltimetz
vector + vectorvector
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
-Return
-decimaldecimal
-floatfloat
-intint
-intervalinterval
date - dateint
date - intdate
date - intervaltimestamp
date - timetimestamp
decimal - decimaldecimal
decimal - intdecimal
float - floatfloat
inet - inetint
inet - intinet
int - decimaldecimal
int - intint
interval - intervalinterval
jsonb - intjsonb
jsonb - stringjsonb
jsonb - string[]jsonb
pg_lsn - decimalpg_lsn
pg_lsn - pg_lsndecimal
time - intervaltime
time - timeinterval
timestamp - intervaltimestamp
timestamp - timestampinterval
timestamp - timestamptzinterval
timestamptz - intervaltimestamptz
timestamptz - timestampinterval
timestamptz - timestamptzinterval
timetz - intervaltimetz
vector - vectorvector
+ + + + + +
->Return
jsonb -> intjsonb
jsonb -> stringjsonb
+ + + + + +
->>Return
jsonb ->> intstring
jsonb ->> stringstring
+ + + + + + + + + + +
/Return
decimal / decimaldecimal
decimal / intdecimal
float / floatfloat
int / decimaldecimal
int / intdecimal
interval / floatinterval
interval / intinterval
+ + + + + + + + +
//Return
decimal // decimaldecimal
decimal // intdecimal
float // floatfloat
int // decimaldecimal
int // intint
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<Return
anyenum < anyenumbool
bool < boolbool
bool[] < bool[]bool
box2d < box2dbool
bpchar < bpcharbool
bytes < bytesbool
bytes[] < bytes[]bool
collatedstring < collatedstringbool
collatedstring{*} < collatedstring{*}bool
date < datebool
date < timestampbool
date < timestamptzbool
date[] < date[]bool
decimal < decimalbool
decimal < floatbool
decimal < intbool
decimal[] < decimal[]bool
float < decimalbool
float < floatbool
float < intbool
float[] < float[]bool
geography < geographybool
geometry < geometrybool
inet < inetbool
inet[] < inet[]bool
int < decimalbool
int < floatbool
int < intbool
int < oidbool
int[] < int[]bool
interval < intervalbool
interval[] < interval[]bool
jsonb < jsonbbool
oid < intbool
oid < oidbool
pg_lsn < pg_lsnbool
refcursor < refcursorbool
string < stringbool
string[] < string[]bool
time < timebool
time < timetzbool
time[] < time[]bool
timestamp < datebool
timestamp < timestampbool
timestamp < timestamptzbool
timestamp[] < timestamp[]bool
timestamptz < datebool
timestamptz < timestampbool
timestamptz < timestamptzbool
timestamptz < timestamptzbool
timetz < timebool
timetz < timetzbool
tuple < tuplebool
uuid < uuidbool
uuid[] < uuid[]bool
varbit < varbitbool
vector < vectorbool
+ + + + +
<#>Return
vector <#> vectorfloat
+ + + + +
<->Return
vector <-> vectorfloat
+ + + + + + +
<<Return
inet << inetbool
int << intint
varbit << intvarbit
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<=Return
anyenum <= anyenumbool
bool <= boolbool
bool[] <= bool[]bool
box2d <= box2dbool
bpchar <= bpcharbool
bytes <= bytesbool
bytes[] <= bytes[]bool
collatedstring <= collatedstringbool
collatedstring{*} <= collatedstring{*}bool
date <= datebool
date <= timestampbool
date <= timestamptzbool
date[] <= date[]bool
decimal <= decimalbool
decimal <= floatbool
decimal <= intbool
decimal[] <= decimal[]bool
float <= decimalbool
float <= floatbool
float <= intbool
float[] <= float[]bool
geography <= geographybool
geometry <= geometrybool
inet <= inetbool
inet[] <= inet[]bool
int <= decimalbool
int <= floatbool
int <= intbool
int <= oidbool
int[] <= int[]bool
interval <= intervalbool
interval[] <= interval[]bool
jsonb <= jsonbbool
oid <= intbool
oid <= oidbool
pg_lsn <= pg_lsnbool
refcursor <= refcursorbool
string <= stringbool
string[] <= string[]bool
time <= timebool
time <= timetzbool
time[] <= time[]bool
timestamp <= datebool
timestamp <= timestampbool
timestamp <= timestamptzbool
timestamp[] <= timestamp[]bool
timestamptz <= datebool
timestamptz <= timestampbool
timestamptz <= timestamptzbool
timestamptz <= timestamptzbool
timetz <= timebool
timetz <= timetzbool
tuple <= tuplebool
uuid <= uuidbool
uuid[] <= uuid[]bool
varbit <= varbitbool
vector <= vectorbool
+ + + + +
<=>Return
vector <=> vectorfloat
+ + + + + +
<@Return
anyelement <@ anyelementbool
jsonb <@ jsonbbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
=Return
anyenum = anyenumbool
bool = boolbool
bool[] = bool[]bool
box2d = box2dbool
bpchar = bpcharbool
bytes = bytesbool
bytes[] = bytes[]bool
collatedstring = collatedstringbool
collatedstring{*} = collatedstring{*}bool
date = datebool
date = timestampbool
date = timestamptzbool
date[] = date[]bool
decimal = decimalbool
decimal = floatbool
decimal = intbool
decimal[] = decimal[]bool
float = decimalbool
float = floatbool
float = intbool
float[] = float[]bool
geography = geographybool
geometry = geometrybool
inet = inetbool
inet[] = inet[]bool
int = decimalbool
int = floatbool
int = intbool
int = oidbool
int[] = int[]bool
interval = intervalbool
interval[] = interval[]bool
jsonb = jsonbbool
oid = intbool
oid = oidbool
pg_lsn = pg_lsnbool
refcursor = refcursorbool
string = stringbool
string[] = string[]bool
time = timebool
time = timetzbool
time[] = time[]bool
timestamp = datebool
timestamp = timestampbool
timestamp = timestamptzbool
timestamp[] = timestamp[]bool
timestamptz = datebool
timestamptz = timestampbool
timestamptz = timestamptzbool
timestamptz = timestamptzbool
timetz = timebool
timetz = timetzbool
tsquery = tsquerybool
tsvector = tsvectorbool
tuple = tuplebool
uuid = uuidbool
uuid[] = uuid[]bool
varbit = varbitbool
vector = vectorbool
+ + + + + + +
>>Return
inet >> inetbool
int >> intint
varbit >> intvarbit
+ + + + +
?Return
jsonb ? stringbool
+ + + + +
?&Return
jsonb ?& string[]bool
+ + + + +
?|Return
jsonb ?| string[]bool
+ + + + + +
@>Return
anyelement @> anyelementbool
jsonb @> jsonbbool
+ + + + + +
@@Return
tsquery @@ tsvectorbool
tsvector @@ tsquerybool
+ + + + +
ILIKEReturn
string ILIKE stringbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
INReturn
anyenum IN tuplebool
bool IN tuplebool
box2d IN tuplebool
bpchar IN tuplebool
bytes IN tuplebool
collatedstring IN tuplebool
date IN tuplebool
decimal IN tuplebool
float IN tuplebool
geography IN tuplebool
geometry IN tuplebool
inet IN tuplebool
int IN tuplebool
interval IN tuplebool
jsonb IN tuplebool
oid IN tuplebool
pg_lsn IN tuplebool
refcursor IN tuplebool
string IN tuplebool
time IN tuplebool
timestamp IN tuplebool
timestamptz IN tuplebool
timetz IN tuplebool
tuple IN tuplebool
uuid IN tuplebool
varbit IN tuplebool
vector IN tuplebool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IS NOT DISTINCT FROMReturn
anyelement IS NOT DISTINCT FROM unknownbool
anyenum IS NOT DISTINCT FROM anyenumbool
bool IS NOT DISTINCT FROM boolbool
bool[] IS NOT DISTINCT FROM bool[]bool
box2d IS NOT DISTINCT FROM box2dbool
bpchar IS NOT DISTINCT FROM bpcharbool
bytes IS NOT DISTINCT FROM bytesbool
bytes[] IS NOT DISTINCT FROM bytes[]bool
collatedstring IS NOT DISTINCT FROM collatedstringbool
collatedstring{*} IS NOT DISTINCT FROM collatedstring{*}bool
date IS NOT DISTINCT FROM datebool
date IS NOT DISTINCT FROM timestampbool
date IS NOT DISTINCT FROM timestamptzbool
date[] IS NOT DISTINCT FROM date[]bool
decimal IS NOT DISTINCT FROM decimalbool
decimal IS NOT DISTINCT FROM floatbool
decimal IS NOT DISTINCT FROM intbool
decimal[] IS NOT DISTINCT FROM decimal[]bool
float IS NOT DISTINCT FROM decimalbool
float IS NOT DISTINCT FROM floatbool
float IS NOT DISTINCT FROM intbool
float[] IS NOT DISTINCT FROM float[]bool
geography IS NOT DISTINCT FROM geographybool
geometry IS NOT DISTINCT FROM geometrybool
inet IS NOT DISTINCT FROM inetbool
inet[] IS NOT DISTINCT FROM inet[]bool
int IS NOT DISTINCT FROM decimalbool
int IS NOT DISTINCT FROM floatbool
int IS NOT DISTINCT FROM intbool
int IS NOT DISTINCT FROM oidbool
int[] IS NOT DISTINCT FROM int[]bool
interval IS NOT DISTINCT FROM intervalbool
interval[] IS NOT DISTINCT FROM interval[]bool
jsonb IS NOT DISTINCT FROM jsonbbool
oid IS NOT DISTINCT FROM intbool
oid IS NOT DISTINCT FROM oidbool
pg_lsn IS NOT DISTINCT FROM pg_lsnbool
refcursor IS NOT DISTINCT FROM refcursorbool
string IS NOT DISTINCT FROM stringbool
string[] IS NOT DISTINCT FROM string[]bool
time IS NOT DISTINCT FROM timebool
time IS NOT DISTINCT FROM timetzbool
time[] IS NOT DISTINCT FROM time[]bool
timestamp IS NOT DISTINCT FROM datebool
timestamp IS NOT DISTINCT FROM timestampbool
timestamp IS NOT DISTINCT FROM timestamptzbool
timestamp[] IS NOT DISTINCT FROM timestamp[]bool
timestamptz IS NOT DISTINCT FROM datebool
timestamptz IS NOT DISTINCT FROM timestampbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timetz IS NOT DISTINCT FROM timebool
timetz IS NOT DISTINCT FROM timetzbool
tsquery IS NOT DISTINCT FROM tsquerybool
tsvector IS NOT DISTINCT FROM tsvectorbool
tuple IS NOT DISTINCT FROM tuplebool
unknown IS NOT DISTINCT FROM unknownbool
unknown IS NOT DISTINCT FROM voidbool
uuid IS NOT DISTINCT FROM uuidbool
uuid[] IS NOT DISTINCT FROM uuid[]bool
varbit IS NOT DISTINCT FROM varbitbool
vector IS NOT DISTINCT FROM vectorbool
void IS NOT DISTINCT FROM unknownbool
+ + + + +
LIKEReturn
string LIKE stringbool
+ + + + +
SIMILAR TOReturn
string SIMILAR TO stringbool
+ + + + + + + + +
^Return
decimal ^ decimaldecimal
decimal ^ intdecimal
float ^ floatfloat
int ^ decimaldecimal
int ^ intint
+ + + + + + +
|Return
inet | inetinet
int | intint
varbit | varbitvarbit
+ + + + + +
|/Return
|/decimaldecimal
|/floatfloat
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
||Return
bool || bool[]bool[]
bool || stringstring
bool[] || boolbool[]
bool[] || bool[]bool[]
box2d || box2dbox2d
box2d || stringstring
bytes || bytesbytes
bytes || bytes[]bytes[]
bytes[] || bytesbytes[]
bytes[] || bytes[]bytes[]
date || date[]date[]
date || stringstring
date[] || datedate[]
date[] || date[]date[]
decimal || decimal[]decimal[]
decimal || stringstring
decimal[] || decimaldecimal[]
decimal[] || decimal[]decimal[]
float || float[]float[]
float || stringstring
float[] || floatfloat[]
float[] || float[]float[]
geography || geographygeography
geography || stringstring
geometry || geometrygeometry
geometry || stringstring
inet || inet[]inet[]
inet || stringstring
inet[] || inetinet[]
inet[] || inet[]inet[]
int || int[]int[]
int || stringstring
int[] || intint[]
int[] || int[]int[]
interval || interval[]interval[]
interval || stringstring
interval[] || intervalinterval[]
interval[] || interval[]interval[]
jsonb || jsonbjsonb
jsonb || stringstring
oid || oidoid
oid || stringstring
pg_lsn || pg_lsnpg_lsn
pg_lsn || stringstring
refcursor || refcursorrefcursor
refcursor || stringstring
string || boolstring
string || box2dstring
string || datestring
string || decimalstring
string || floatstring
string || geographystring
string || geometrystring
string || inetstring
string || intstring
string || intervalstring
string || jsonbstring
string || oidstring
string || pg_lsnstring
string || refcursorstring
string || stringstring
string || string[]string[]
string || timestring
string || timestampstring
string || timestamptzstring
string || timetzstring
string || tuplestring
string || uuidstring
string || varbitstring
string[] || stringstring[]
string[] || string[]string[]
time || stringstring
time || time[]time[]
time[] || timetime[]
time[] || time[]time[]
timestamp || stringstring
timestamp || timestamp[]timestamp[]
timestamp[] || timestamptimestamp[]
timestamp[] || timestamp[]timestamp[]
timestamptz || stringstring
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timetz || stringstring
timetz || timetztimetz
tuple || stringstring
uuid || stringstring
uuid || uuid[]uuid[]
uuid[] || uuiduuid[]
uuid[] || uuid[]uuid[]
varbit || stringstring
varbit || varbitvarbit
+ + + + + +
||/Return
||/decimaldecimal
||/floatfloat
+ + + + + + + + + + + +
~Return
~inetinet
~intint
~varbitvarbit
box2d ~ box2dbool
box2d ~ geometrybool
geometry ~ box2dbool
geometry ~ geometrybool
string ~ stringbool
+ + + + +
~*Return
string ~* stringbool
diff --git a/src/current/_includes/cockroach-generated/release-25.1/sql/window_functions.md b/src/current/_includes/cockroach-generated/release-25.1/sql/window_functions.md new file mode 100644 index 00000000000..e1032ff82de --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.1/sql/window_functions.md @@ -0,0 +1,413 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cume_dist() → float

Calculates the relative rank of the current row: (number of rows preceding or peer with current row) / (total rows).

+		Immutable
dense_rank() → int

Calculates the rank of the current row without gaps; this function counts peer groups.

+		Immutable
first_value(val: bool) → bool

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: bytes) → bytes

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: date) → date

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: decimal) → decimal

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: float) → float

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: inet) → inet

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: int) → int

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: interval) → interval

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: string) → string

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: time) → time

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: uuid) → uuid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: box2d) → box2d

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geography) → geography

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geometry) → geometry

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: oid) → oid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timetz) → timetz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: varbit) → varbit

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
lag(val: bool) → bool

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: bytes) → bytes

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: date) → date

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: date, n: int) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: decimal) → decimal

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: float) → float

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: float, n: int) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: inet) → inet

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: int) → int

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: int, n: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: interval) → interval

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: string) → string

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: string, n: int) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: time) → time

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: time, n: int) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamp) → timestamp

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz) → timestamptz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: uuid) → uuid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: box2d) → box2d

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geography) → geography

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geometry) → geometry

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: jsonb) → jsonb

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: oid) → oid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn) → pg_lsn

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: refcursor) → refcursor

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timetz) → timetz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: varbit) → varbit

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
last_value(val: bool) → bool

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: bytes) → bytes

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: date) → date

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: decimal) → decimal

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: float) → float

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: inet) → inet

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: int) → int

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: interval) → interval

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: string) → string

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: time) → time

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: uuid) → uuid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: box2d) → box2d

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geography) → geography

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geometry) → geometry

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: oid) → oid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timetz) → timetz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: varbit) → varbit

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
lead(val: bool) → bool

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: bytes) → bytes

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: date) → date

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: date, n: int) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: decimal) → decimal

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: float) → float

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: float, n: int) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: inet) → inet

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: int) → int

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: int, n: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: interval) → interval

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: string) → string

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: string, n: int) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: time) → time

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: time, n: int) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamp) → timestamp

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz) → timestamptz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: uuid) → uuid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: box2d) → box2d

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geography) → geography

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geometry) → geometry

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: jsonb) → jsonb

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: oid) → oid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn) → pg_lsn

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: refcursor) → refcursor

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timetz) → timetz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: varbit) → varbit

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
nth_value(val: bool, n: int) → bool

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: bytes, n: int) → bytes

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: date, n: int) → date

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: decimal, n: int) → decimal

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: float, n: int) → float

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: inet, n: int) → inet

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: int, n: int) → int

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: interval, n: int) → interval

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: string, n: int) → string

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: time, n: int) → time

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: uuid, n: int) → uuid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: box2d, n: int) → box2d

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geography, n: int) → geography

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geometry, n: int) → geometry

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: oid, n: int) → oid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timetz, n: int) → timetz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: varbit, n: int) → varbit

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
ntile(n: int) → int

Calculates an integer ranging from 1 to n, dividing the partition as equally as possible.

+		Immutable
percent_rank() → float

Calculates the relative rank of the current row: (rank - 1) / (total rows - 1).

+		Immutable
rank() → int

Calculates the rank of the current row with gaps; same as row_number of its first peer.

+		Immutable
row_number() → int

Calculates the number of the current row within its partition, counting from 1.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-25.2/eventlog.md b/src/current/_includes/cockroach-generated/release-25.2/eventlog.md new file mode 100644 index 00000000000..8960a62b59b --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.2/eventlog.md @@ -0,0 +1,3526 @@ +Certain notable events are reported using a structured format. +Commonly, these notable events are also copied to the table +`system.eventlog`, unless the cluster setting +`server.eventlog.enabled` is unset. + +Additionally, notable events are copied to specific external logging +channels in log messages, where they can be collected for further processing. + +The sections below document the possible notable event types +in this version of CockroachDB. For each event type, a table +documents the possible fields. A field may be omitted from +an event if its value is empty or zero. + +A field is also considered "Sensitive" if it may contain +application-specific information or personally identifiable information (PII). In that case, +the copy of the event sent to the external logging channel +will contain redaction markers in a format that is compatible +with the redaction facilities in [`cockroach debug zip`](cockroach-debug-zip.html) +and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html), +provided the `redactable` functionality is enabled on the logging sink. + +Events not documented on this page will have an unstructured format in log messages. + +## Changefeed telemetry events + +Events in this category pertain to changefeed usage and metrics. + +Events in this category are logged to the `TELEMETRY` channel. + + +### `changefeed_canceled` + +An event of type `changefeed_canceled` is an event for any changefeed cancellations. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `changefeed_emitted_bytes` + +An event of type `changefeed_emitted_bytes` is an event representing the bytes emitted by a changefeed over an interval. + + +| Field | Description | Sensitive | +|--|--|--| +| `EmittedBytes` | The number of bytes emitted. | no | +| `EmittedMessages` | The number of messages emitted. | no | +| `LoggingInterval` | The time period in nanoseconds between emitting telemetry events of this type (per-aggregator). | no | +| `Closing` | Flag to indicate that the changefeed is closing. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `changefeed_failed` + +An event of type `changefeed_failed` is an event for any changefeed failure since the plan hook +was triggered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FailureType` | The reason / environment with which the changefeed failed (ex: connection_closed, changefeed_behind). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `create_changefeed` + +An event of type `create_changefeed` is an event for any CREATE CHANGEFEED query that +successfully starts running. Failed CREATE statements will show up as +ChangefeedFailed events. + + +| Field | Description | Sensitive | +|--|--|--| +| `Transformation` | Flag representing whether the changefeed is using CDC queries. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +## Cluster-level events + +Events in this category pertain to an entire cluster and are +not relative to any particular tenant. + +In a multi-tenant setup, the `system.eventlog` table for individual +tenants cannot contain a copy of cluster-level events; conversely, +the `system.eventlog` table in the system tenant cannot contain the +SQL-level events for individual tenants. + +Events in this category are logged to the `OPS` channel. + + +### `certs_reload` + +An event of type `certs_reload` is recorded when the TLS certificates are +reloaded/rotated from disk. + + +| Field | Description | Sensitive | +|--|--|--| +| `Success` | Whether the operation completed without errors. | no | +| `ErrorMessage` | If an error was encountered, the text of the error. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `disk_slowness_cleared` + +An event of type `disk_slowness_cleared` is recorded when disk slowness in a store has cleared. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `disk_slowness_detected` + +An event of type `disk_slowness_detected` is recorded when a store observes disk slowness +events. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `low_disk_space` + +An event of type `low_disk_space` is emitted when a store is reaching capacity, as we reach +certain thresholds. It is emitted periodically while we are in a low disk +state. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | +| `PercentThreshold` | The free space percent threshold that we went under. | no | +| `AvailableBytes` | | no | +| `TotalBytes` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `node_decommissioned` + +An event of type `node_decommissioned` is recorded when a node is marked as +decommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_decommissioning` + +An event of type `node_decommissioning` is recorded when a node is marked as +decommissioning. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_join` + +An event of type `node_join` is recorded when a node joins the cluster. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_recommissioned` + +An event of type `node_recommissioned` is recorded when a decommissioning node is +recommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_restart` + +An event of type `node_restart` is recorded when an existing node rejoins the cluster +after being offline. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_connection_timeout` + +An event of type `node_shutdown_connection_timeout` is recorded when SQL connections remain open +during shutdown, after waiting for the server.shutdown.connections.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still open after waiting for the client to close them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.connections.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_transaction_timeout` + +An event of type `node_shutdown_transaction_timeout` is recorded when SQL transactions remain open +during shutdown, after waiting for the server.shutdown.transactions.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still running SQL transactions after waiting for the client to end them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.transactions.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `tenant_shared_service_start` + +An event of type `tenant_shared_service_start` is recorded when a tenant server +is started inside the same process as the KV layer. + + +| Field | Description | Sensitive | +|--|--|--| +| `OK` | Whether the startup was successful. | no | +| `ErrorText` | If the startup failed, the text of the error. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +### `tenant_shared_service_stop` + +An event of type `tenant_shared_service_stop` is recorded when a tenant server +is shut down inside the same process as the KV layer. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +## Debugging events + +Events in this category pertain to debugging operations performed by +operators or (more commonly) Cockroach Labs employees. These operations can +e.g. directly access and mutate internal state, breaking system invariants. + +Events in this category are logged to the `OPS` channel. + + +### `debug_recover_replica` + +An event of type `debug_recover_replica` is recorded when unsafe loss of quorum recovery is performed. + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `StoreID` | | no | +| `SurvivorReplicaID` | | no | +| `UpdatedReplicaID` | | no | +| `StartKey` | | yes | +| `EndKey` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +### `debug_send_kv_batch` + +An event of type `debug_send_kv_batch` is recorded when an arbitrary KV BatchRequest is submitted +to the cluster via the `debug send-kv-batch` CLI command. + + +| Field | Description | Sensitive | +|--|--|--| +| `BatchRequest` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +## Health events + +Events in this category pertain to the health of one or more servers. + +Events in this category are logged to the `HEALTH` channel. + + +### `hot_ranges_stats` + +An event of type `hot_ranges_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `Qps` | | no | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | yes | +| `LeaseholderNodeID` | LeaseholderNodeID indicates the Node ID that is the current leaseholder for the given range. | no | +| `WritesPerSecond` | Writes per second is the recent number of keys written per second on this range. | no | +| `ReadsPerSecond` | Reads per second is the recent number of keys read per second on this range. | no | +| `WriteBytesPerSecond` | Write bytes per second is the recent number of bytes written per second on this range. | no | +| `ReadBytesPerSecond` | Read bytes per second is the recent number of bytes read per second on this range. | no | +| `CPUTimePerSecond` | CPU time per second is the recent cpu usage in nanoseconds of this range. | no | +| `Databases` | Databases for the range. | no | +| `Tables` | Tables for the range | no | +| `Indexes` | Indexes for the range | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `runtime_stats` + +An event of type `runtime_stats` is recorded every 10 seconds as server health metrics. + + +| Field | Description | Sensitive | +|--|--|--| +| `MemRSSBytes` | The process resident set size. Expressed as bytes. | no | +| `GoroutineCount` | The number of goroutines. | no | +| `MemStackSysBytes` | The stack system memory used. Expressed as bytes. | no | +| `GoAllocBytes` | The memory allocated by Go. Expressed as bytes. | no | +| `GoTotalBytes` | The total memory allocated by Go but not released. Expressed as bytes. | no | +| `GoStatsStaleness` | The staleness of the Go memory statistics. Expressed in seconds. | no | +| `HeapFragmentBytes` | The amount of heap fragmentation. Expressed as bytes. | no | +| `HeapReservedBytes` | The amount of heap reserved. Expressed as bytes. | no | +| `HeapReleasedBytes` | The amount of heap released. Expressed as bytes. | no | +| `CGoAllocBytes` | The memory allocated outside of Go. Expressed as bytes. | no | +| `CGoTotalBytes` | The total memory allocated outside of Go but not released. Expressed as bytes. | no | +| `CGoCallRate` | The total number of calls outside of Go over time. Expressed as operations per second. | no | +| `CPUUserPercent` | The user CPU percentage. | no | +| `CPUSysPercent` | The system CPU percentage. | no | +| `GCPausePercent` | The GC pause percentage. | no | +| `GCRunCount` | The total number of GC runs. | no | +| `NetHostRecvBytes` | The bytes received on all network interfaces since this process started. | no | +| `NetHostSendBytes` | The bytes sent on all network interfaces since this process started. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Job events + +Events in this category pertain to long-running jobs that are orchestrated by +a node's job registry. These system processes can create and/or modify stored +objects during the course of their execution. + +A job might choose to emit multiple events during its execution when +transitioning from one "state" to another. +Egs: IMPORT/RESTORE will emit events on job creation and successful +completion. If the job fails, events will be emitted on job creation, +failure, and successful revert. + +Events in this category are logged to the `OPS` channel. + + +### `import` + +An event of type `import` is recorded when an import job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `restore` + +An event of type `restore` is recorded when a restore job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `status_change` + +An event of type `status_change` is recorded when a job changes statuses. + + +| Field | Description | Sensitive | +|--|--|--| +| `JobID` | The ID of the job that is changing statuses. | no | +| `JobType` | The type of the job that is changing statuses. | no | +| `Description` | A human parsable description of the status change | partially | +| `PreviousStatus` | The status that the job is transitioning out of | no | +| `NewStatus` | The status that the job has transitioned into | no | +| `RunNum` | The run number of the job. | no | +| `Error` | An error that may have occurred while the job was running. | yes | +| `FinalResumeErr` | An error that occurred that requires the job to be reverted. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Miscellaneous SQL events + +Events in this category report miscellaneous SQL events. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own system.eventlog table. + +Events in this category are logged to the `OPS` channel. + + +### `set_cluster_setting` + +An event of type `set_cluster_setting` is recorded when a cluster setting is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `set_tenant_cluster_setting` + +An event of type `set_tenant_cluster_setting` is recorded when a cluster setting override +is changed, either for another tenant or for all tenants. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | +| `TenantId` | The target Tenant ID. Empty if targeting all tenants. | no | +| `AllTenants` | Whether the override applies to all tenants. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +## SQL Access Audit Events + +Events in this category are generated when a table has been +marked as audited via `ALTER TABLE ... EXPERIMENTAL_AUDIT SET`. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SENSITIVE_ACCESS` channel. + + +### `admin_query` + +An event of type `admin_query` is recorded when a user with admin privileges (the user +is directly or indirectly a member of the admin role) executes a query. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `role_based_audit_event` + +An event of type `role_based_audit_event` is an audit event recorded when an executed query belongs to a user whose role +membership(s) correspond to any role that is enabled to emit an audit log via the sql.log.user_audit +cluster setting. + + +| Field | Description | Sensitive | +|--|--|--| +| `Role` | The configured audit role that emitted this log. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sensitive_table_access` + +An event of type `sensitive_table_access` is recorded when an access is performed to +a table marked as audited. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table being audited. | yes | +| `AccessMode` | How the table was accessed (r=read / rw=read/write). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +## SQL Execution Log + +Events in this category report executed queries. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `query_execute` + +An event of type `query_execute` is recorded when a query is executed, +and the cluster setting `sql.log.all_statements.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +## SQL Logical Schema Changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the SQL logical +schema. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SQL_SCHEMA` channel. + + +### `alter_database_add_region` + +An event of type `alter_database_add_region` is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `RegionName` | The region being added. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_drop_region` + +AlterDatabaseAddRegion is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `RegionName` | The region being dropped. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_placement` + +An event of type `alter_database_placement` is recorded when the database placement is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `Placement` | The new placement policy. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_primary_region` + +An event of type `alter_database_primary_region` is recorded when a primary region is added/modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `PrimaryRegionName` | The new primary region. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_set_zone_config_extension` + +An event of type `alter_database_set_zone_config_extension` is recorded when a zone config extension is changed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `alter_database_survival_goal` + +An event of type `alter_database_survival_goal` is recorded when the survival goal is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `SurvivalGoal` | The new survival goal | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_function_options` + +An event of type `alter_function_options` is recorded when a user-defined function's options are +altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the affected function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_index` + +An event of type `alter_index` is recorded when an index is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_index_visible` + +AlterIndex is recorded when an index visibility is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `NotVisible` | Set true if index is not visible. NOTE: THIS FIELD IS DEPRECATED in favor of invisibility. | no | +| `Invisibility` | The new invisibility of the affected index. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_sequence` + +An event of type `alter_sequence` is recorded when a sequence is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_table` + +An event of type `alter_table` is recorded when a table is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update, if any. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_type` + +EventAlterType is recorded when a user-defined type is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_column` + +An event of type `comment_on_column` is recorded when a column is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected column. | no | +| `ColumnName` | The affected column. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_constraint` + +An event of type `comment_on_constraint` is recorded when an constraint is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected constraint. | no | +| `ConstraintName` | The name of the affected constraint. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_database` + +CommentOnTable is recorded when a database is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_index` + +An event of type `comment_on_index` is recorded when an index is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_schema` + + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | Name of the affected schema. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_table` + +An event of type `comment_on_table` is recorded when a table is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_type` + +An event of type `comment_on_type` is recorded when a type is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_database` + +An event of type `create_database` is recorded when a database is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the new database. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_function` + +An event of type `create_function` is recorded when a user-defined function is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the created function. | no | +| `IsReplace` | If the new function is a replace of an existing function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_index` + +An event of type `create_index` is recorded when an index is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the new index. | no | +| `IndexName` | The name of the new index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_policy` + +An event of type `create_policy` is recorded when a policy is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the policy's table. | no | +| `PolicyName` | Name of the created policy. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_schema` + +An event of type `create_schema` is recorded when a schema is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the new schema. | no | +| `Owner` | The name of the owner for the new schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_sequence` + +An event of type `create_sequence` is recorded when a sequence is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the new sequence. | no | +| `Owner` | The name of the owner for the new sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_statistics` + +An event of type `create_statistics` is recorded when statistics are collected for a +table. + +Events of this type are only collected when the cluster setting +`sql.stats.post_events.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table for which the statistics were created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_table` + +An event of type `create_table` is recorded when a table is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the new table. | no | +| `Owner` | The name of the owner for the new table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_trigger` + +An event of type `create_trigger` is recorded when a trigger is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the trigger's table. | no | +| `TriggerName` | Name of the created trigger. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_type` + +An event of type `create_type` is recorded when a user-defined type is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the new type. | no | +| `Owner` | The name of the owner for the new type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_view` + +An event of type `create_view` is recorded when a view is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the new view. | no | +| `Owner` | The name of the owner of the new view. | no | +| `ViewQuery` | The SQL selection clause used to define the view. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_database` + +An event of type `drop_database` is recorded when a database is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | no | +| `DroppedSchemaObjects` | The names of the schemas dropped by a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_function` + +An event of type `drop_function` is recorded when a user-defined function is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the dropped function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_index` + +An event of type `drop_index` is recorded when an index is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_policy` + +An event of type `drop_policy` is recorded when a policy is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the policy's table. | no | +| `PolicyName` | Name of the dropped policy. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_schema` + +An event of type `drop_schema` is recorded when a schema is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_sequence` + +An event of type `drop_sequence` is recorded when a sequence is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_table` + +An event of type `drop_table` is recorded when a table is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_trigger` + +An event of type `drop_trigger` is recorded when a trigger is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the trigger's table. | no | +| `TriggerName` | Name of the dropped trigger. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_type` + +An event of type `drop_type` is recorded when a user-defined type is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_view` + +An event of type `drop_view` is recorded when a view is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the affected view. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `finish_schema_change` + +An event of type `finish_schema_change` is recorded when a previously initiated schema +change has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to complete. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `finish_schema_change_rollback` + +An event of type `finish_schema_change_rollback` is recorded when a previously +initiated schema change rollback has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to rollback. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `force_delete_table_data_entry` + + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_database` + +An event of type `rename_database` is recorded when a database is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The old name of the affected database. | no | +| `NewDatabaseName` | The new name of the affected database. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_function` + +An event of type `rename_function` is recorded when a user-defined function is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The old name of the affected function. | no | +| `NewFunctionName` | The new name of the affected function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_schema` + +An event of type `rename_schema` is recorded when a schema is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The old name of the affected schema. | no | +| `NewSchemaName` | The new name of the affected schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_table` + +An event of type `rename_table` is recorded when a table, sequence or view is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The old name of the affected table. | no | +| `NewTableName` | The new name of the affected table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_type` + +An event of type `rename_type` is recorded when a user-defined type is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The old name of the affected type. | no | +| `NewTypeName` | The new name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `reverse_schema_change` + +An event of type `reverse_schema_change` is recorded when an in-progress schema change +encounters a problem and is reversed. + + +| Field | Description | Sensitive | +|--|--|--| +| `Error` | The error encountered that caused the schema change to be reversed. The specific format of the error is variable and can change across releases without warning. | partially | +| `SQLSTATE` | The SQLSTATE code for the error. | no | +| `LatencyNanos` | The amount of time the schema change job took before being reverted. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `set_schema` + +An event of type `set_schema` is recorded when a table, view, sequence or type's schema is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorName` | The old name of the affected descriptor. | no | +| `NewDescriptorName` | The new name of the affected descriptor. | no | +| `DescriptorType` | The descriptor type being changed (table, view, sequence, type). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `truncate_table` + +An event of type `truncate_table` is recorded when a table is truncated. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_delete_descriptor` + +An event of type `unsafe_delete_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_delete_descriptor(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_delete_namespace_entry` + +An event of type `unsafe_delete_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_delete_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_upsert_descriptor` + +An event of type `unsafe_upsert_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_upsert_descriptor(). + + +| Field | Description | Sensitive | +|--|--|--| +| `PreviousDescriptor` | | yes | +| `NewDescriptor` | | yes | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_upsert_namespace_entry` + +An event of type `unsafe_upsert_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_upsert_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `PreviousID` | | no | +| `Force` | | no | +| `FailedValidation` | | no | +| `ValidationErrors` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +## SQL Privilege changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the privilege +grants for stored objects. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `PRIVILEGES` channel. + + +### `alter_database_owner` + +An event of type `alter_database_owner` is recorded when a database's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database being affected. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_default_privileges` + +An event of type `alter_default_privileges` is recorded when default privileges are changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | +| `RoleName` | Either role_name should be populated or for_all_roles should be true. The role having its default privileges altered. | yes | +| `ForAllRoles` | Identifies if FOR ALL ROLES is used. | no | +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `alter_function_owner` + +AlterTableOwner is recorded when the owner of a user-defined function is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The name of the affected user-defined function. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_schema_owner` + +An event of type `alter_schema_owner` is recorded when a schema's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_table_owner` + +An event of type `alter_table_owner` is recorded when the owner of a table, view or sequence is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected object. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_type_owner` + +An event of type `alter_type_owner` is recorded when the owner of a user-defiend type is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `change_database_privilege` + +An event of type `change_database_privilege` is recorded when privileges are +added to / removed from a user for a database object. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_function_privilege` + + + +| Field | Description | Sensitive | +|--|--|--| +| `FuncName` | The name of the affected function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_schema_privilege` + +An event of type `change_schema_privilege` is recorded when privileges are added to / +removed from a user for a schema object. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_table_privilege` + +An event of type `change_table_privilege` is recorded when privileges are added to / removed +from a user for a table, sequence or view object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_type_privilege` + +An event of type `change_type_privilege` is recorded when privileges are added to / +removed from a user for a type object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +## SQL Session events + +Events in this category report SQL client connections +and sessions. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SESSIONS` channel. + + +### `client_authentication_failed` + +An event of type `client_authentication_failed` is reported when a client session +did not authenticate successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Reason` | The reason for the authentication failure. See below for possible values for type `AuthFailReason`. | no | +| `Detail` | The detailed error for the authentication failure. | partially | +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_info` + +An event of type `client_authentication_info` is reported for intermediate +steps during the authentication process. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used, once known. | no | +| `Info` | The authentication progress message. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_ok` + +An event of type `client_authentication_ok` is reported when a client session +was authenticated successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_connection_end` + +An event of type `client_connection_end` is reported when a client connection +is closed. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_connection_start` + +An event of type `client_connection_start` is reported when a client connection +is established. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_session_end` + +An event of type `client_session_end` is reported when a client session +is completed. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +## SQL Slow Query Log + +Events in this category report slow query execution. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_PERF` channel. + + +### `large_row` + +An event of type `large_row` is recorded when a statement tries to write a row larger than +cluster setting `sql.guardrails.max_row_size_log` to the database. Multiple +LargeRow events will be recorded for statements writing multiple large rows. +LargeRow events are recorded before the transaction commits, so in the case +of transaction abort there will not be a corresponding row in the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query` + +An event of type `slow_query` is recorded when a query triggers the "slow query" condition. + +As of this writing, the condition requires: +- the cluster setting `sql.log.slow_query.latency_threshold` +set to a non-zero value, AND +- EITHER of the following conditions: +- the actual age of the query exceeds the configured threshold; AND/OR +- the query performs a full table/index scan AND the cluster setting +`sql.log.slow_query.experimental_full_table_scans.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit` + +An event of type `txn_rows_read_limit` is recorded when a transaction tries to read more rows than +cluster setting `sql.defaults.transaction_rows_read_log`. There will only be +a single record for a single transaction (unless it is retried) even if there +are more statement within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit` + +An event of type `txn_rows_written_limit` is recorded when a transaction tries to write more rows +than cluster setting `sql.defaults.transaction_rows_written_log`. There will +only be a single record for a single transaction (unless it is retried) even +if there are more mutation statements within the transaction that haven't +been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL Slow Query Log (Internal) + +Events in this category report slow query execution by +internal executors, i.e., when CockroachDB internally issues +SQL statements. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_INTERNAL_PERF` channel. + + +### `large_row_internal` + +An event of type `large_row_internal` is recorded when an internal query tries to write a row +larger than cluster settings `sql.guardrails.max_row_size_log` or +`sql.guardrails.max_row_size_err` to the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query_internal` + +An event of type `slow_query_internal` is recorded when a query triggers the "slow query" condition, +and the cluster setting `sql.log.slow_query.internal_queries.enabled` is +set. +See the documentation for the event type `slow_query` for details about +the "slow query" condition. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit_internal` + +An event of type `txn_rows_read_limit_internal` is recorded when an internal transaction tries to +read more rows than cluster setting `sql.defaults.transaction_rows_read_log` +or `sql.defaults.transaction_rows_read_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit_internal` + +An event of type `txn_rows_written_limit_internal` is recorded when an internal transaction tries to +write more rows than cluster setting +`sql.defaults.transaction_rows_written_log` or +`sql.defaults.transaction_rows_written_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL User and Role operations + +Events in this category pertain to SQL statements that modify the +properties of users and roles. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `USER_ADMIN` channel. + + +### `alter_role` + +An event of type `alter_role` is recorded when a role is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | +| `Options` | The options set on the user/role. | no | +| `SetInfo` | Information corresponding to an ALTER ROLE SET statement. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_role` + +An event of type `create_role` is recorded when a role is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the new user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_role` + +An event of type `drop_role` is recorded when a role is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `grant_role` + +An event of type `grant_role` is recorded when a role is granted. + + +| Field | Description | Sensitive | +|--|--|--| +| `GranteeRoles` | The roles being granted to. | yes | +| `Members` | The roles being granted. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `password_hash_converted` + +An event of type `password_hash_converted` is recorded when the password credentials +are automatically converted server-side. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the user/role whose credentials have been converted. | yes | +| `OldMethod` | The previous hash method. | no | +| `NewMethod` | The new hash method. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Storage telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `level_stats` + +An event of type `level_stats` contains per-level statistics for an LSM. + + +| Field | Description | Sensitive | +|--|--|--| +| `Level` | level is the level ID in a LSM (e.g. level(L0) == 0, etc.) | no | +| `NumFiles` | num_files is the number of files in the level (gauge). | no | +| `SizeBytes` | size_bytes is the size of the level, in bytes (gauge). | no | +| `Score` | score is the compaction score of the level (gauge). | no | +| `BytesIn` | bytes_in is the number of bytes written to this level (counter). | no | +| `BytesIngested` | bytes_ingested is the number of bytes ingested into this level (counter). | no | +| `BytesMoved` | bytes_moved is the number of bytes moved into this level via a move-compaction (counter). | no | +| `BytesRead` | bytes_read is the number of bytes read from this level, during compactions (counter). | no | +| `BytesCompacted` | bytes_compacted is the number of bytes written to this level during compactions (counter). | no | +| `BytesFlushed` | bytes flushed is the number of bytes flushed to this level. This value is always zero for levels other than L0 (counter). | no | +| `TablesCompacted` | tables_compacted is the count of tables compacted into this level (counter). | no | +| `TablesFlushed` | tables_flushed is the count of tables flushed into this level (counter). | no | +| `TablesIngested` | tables_ingested is the count of tables ingested into this level (counter). | no | +| `TablesMoved` | tables_moved is the count of tables moved into this level via move-compactions (counter). | no | +| `NumSublevels` | num_sublevel is the count of sublevels for the level. This value is always zero for levels other than L0 (gauge). | no | + + + +### `store_stats` + +An event of type `store_stats` contains per store stats. + +Note that because stats are scoped to the lifetime of the process, counters +(and certain gauges) will be reset across node restarts. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeId` | node_id is the ID of the node. | no | +| `StoreId` | store_id is the ID of the store. | no | +| `Levels` | levels is a nested message containing per-level statistics. | yes | +| `CacheSize` | cache_size is the size of the cache for the store, in bytes (gauge). | no | +| `CacheCount` | cache_count is the number of items in the cache (gauge). | no | +| `CacheHits` | cache_hits is the number of cache hits (counter). | no | +| `CacheMisses` | cache_misses is the number of cache misses (counter). | no | +| `CompactionCountDefault` | compaction_count_default is the count of default compactions (counter). | no | +| `CompactionCountDeleteOnly` | compaction_count_delete_only is the count of delete-only compactions (counter). | no | +| `CompactionCountElisionOnly` | compaction_count_elision_only is the count of elision-only compactions (counter). | no | +| `CompactionCountMove` | compaction_count_move is the count of move-compactions (counter). | no | +| `CompactionCountRead` | compaction_count_read is the count of read-compactions (counter). | no | +| `CompactionCountRewrite` | compaction_count_rewrite is the count of rewrite-compactions (counter). | no | +| `CompactionNumInProgress` | compactions_num_in_progress is the number of compactions in progress (gauge). | no | +| `CompactionMarkedFiles` | compaction_marked_files is the count of files marked for compaction (gauge). | no | +| `FlushCount` | flush_count is the number of flushes (counter). | no | +| `FlushIngestCount` | | no | +| `FlushIngestTableCount` | | no | +| `FlushIngestTableBytes` | | no | +| `IngestCount` | ingest_count is the number of successful ingest operations (counter). | no | +| `MemtableSize` | memtable_size is the total size allocated to all memtables and (large) batches, in bytes (gauge). | no | +| `MemtableCount` | memtable_count is the count of memtables (gauge). | no | +| `MemtableZombieCount` | memtable_zombie_count is the count of memtables no longer referenced by the current DB state, but still in use by an iterator (gauge). | no | +| `MemtableZombieSize` | memtable_zombie_size is the size, in bytes, of all zombie memtables (gauge). | no | +| `WalLiveCount` | wal_live_count is the count of live WAL files (gauge). | no | +| `WalLiveSize` | wal_live_size is the size, in bytes, of live data in WAL files. With WAL recycling, this value is less than the actual on-disk size of the WAL files (gauge). | no | +| `WalObsoleteCount` | wal_obsolete_count is the count of obsolete WAL files (gauge). | no | +| `WalObsoleteSize` | wal_obsolete_size is the size of obsolete WAL files, in bytes (gauge). | no | +| `WalPhysicalSize` | wal_physical_size is the size, in bytes, of the WAL files on disk (gauge). | no | +| `WalBytesIn` | wal_bytes_in is the number of logical bytes written to the WAL (counter). | no | +| `WalBytesWritten` | wal_bytes_written is the number of bytes written to the WAL (counter). | no | +| `TableObsoleteCount` | table_obsolete_count is the number of tables which are no longer referenced by the current DB state or any open iterators (gauge). | no | +| `TableObsoleteSize` | table_obsolete_size is the size, in bytes, of obsolete tables (gauge). | no | +| `TableZombieCount` | table_zombie_count is the number of tables no longer referenced by the current DB state, but are still in use by an open iterator (gauge). | no | +| `TableZombieSize` | table_zombie_size is the size, in bytes, of zombie tables (gauge). | no | +| `RangeKeySetsCount` | range_key_sets_count is the approximate count of internal range key sets in the store. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `captured_index_usage_stats` + +An event of type `captured_index_usage_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `TotalReadCount` | TotalReadCount is the number of times the index has been read. | no | +| `LastRead` | LastRead is the timestamp at which the index was last read. | no | +| `TableID` | TableID is the ID of the table on which the index was created. This is same as descpb.TableID and is unique within the cluster. | no | +| `IndexID` | IndexID is the ID of the index within the scope of the given table. | no | +| `DatabaseName` | DatabaseName is the name of the database in which the index was created. | no | +| `TableName` | TableName is the name of the table on which the index was created. | no | +| `IndexName` | IndexName is the name of the index within the scope of the given table. | no | +| `IndexType` | IndexType is the type of the index. Index types include "primary" and "secondary". | no | +| `IsUnique` | IsUnique indicates if the index has a UNIQUE constraint. | no | +| `IsInverted` | IsInverted indicates if the index is an inverted index. | no | +| `CreatedAt` | CreatedAt is the timestamp at which the index was created. | no | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `m_v_c_c_iterator_stats` + +Internal storage iteration statistics for a single execution. + + +| Field | Description | Sensitive | +|--|--|--| +| `StepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `StepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `BlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `BlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `KeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `ValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | + + + +### `recovery_event` + +An event of type `recovery_event` is an event that is logged on every invocation of BACKUP, +RESTORE, and on every BACKUP schedule creation, with the appropriate subset +of fields populated depending on the type of event. This event is is also +logged whenever a BACKUP and RESTORE job completes or fails. + + +| Field | Description | Sensitive | +|--|--|--| +| `RecoveryType` | RecoveryType is the type of recovery described by this event, which is one of - backup - scheduled_backup - create_schedule - restore

It can also be a job event corresponding to the recovery, which is one of - backup_job - scheduled_backup_job - restore_job | no | +| `TargetScope` | TargetScope is the largest scope of the targets that the user is backing up or restoring based on the following order: table < schema < database < full cluster. | no | +| `IsMultiregionTarget` | IsMultiregionTarget is true if any of the targets contain objects with multi-region primitives. | no | +| `TargetCount` | TargetCount is the number of targets the in the BACKUP/RESTORE. | no | +| `DestinationSubdirType` | DestinationSubdirType is - latest: if using the latest subdir - standard: if using a date-based subdir - custom: if using a custom subdir that's not date-based | no | +| `DestinationStorageTypes` | DestinationStorageTypes are the types of storage that the user is backing up to or restoring from. | no | +| `DestinationAuthTypes` | DestinationAuthTypes are the types of authentication methods that the user is using to access the destination storage. | no | +| `IsLocalityAware` | IsLocalityAware indicates if the BACKUP or RESTORE is locality aware. | no | +| `AsOfInterval` | AsOfInterval is the time interval in nanoseconds between the statement timestamp and the timestamp resolved by the AS OF SYSTEM TIME expression. The interval is expressed in nanoseconds. | no | +| `WithRevisionHistory` | WithRevisionHistory is true if the BACKUP includes revision history. | no | +| `HasEncryptionPassphrase` | HasEncryptionPassphrase is true if the user provided an encryption passphrase to encrypt/decrypt their backup. | no | +| `KMSType` | KMSType is the type of KMS the user is using to encrypt/decrypt their backup. | no | +| `KMSCount` | KMSCount is the number of KMS the user is using. | no | +| `Options` | Options contain all the names of the options specified by the user in the BACKUP or RESTORE statement. For options that are accompanied by a value, only those with non-empty values will be present.

It's important to note that there are no option values anywhere in the event payload. Future changes to telemetry should refrain from adding values to the payload unless they are properly redacted. | no | +| `DebugPauseOn` | DebugPauseOn is the type of event that the restore should pause on for debugging purposes. Currently only "error" is supported. | no | +| `JobID` | JobID is the ID of the BACKUP/RESTORE job. | no | +| `ResultStatus` | ResultStatus indicates whether the job succeeded or failed. | no | +| `ErrorText` | ErrorText is the text of the error that caused the job to fail. | partially | +| `RecurringCron` | RecurringCron is the crontab for the incremental backup. | no | +| `FullBackupCron` | FullBackupCron is the crontab for the full backup. | no | +| `CustomFirstRunTime` | CustomFirstRunTime is the timestamp for the user configured first run time. Expressed as nanoseconds since the Unix epoch. | no | +| `OnExecutionFailure` | OnExecutionFailure describes the desired behavior if the schedule fails to execute. | no | +| `OnPreviousRunning` | OnPreviousRunning describes the desired behavior if the previously scheduled BACKUP is still running. | no | +| `IgnoreExistingBackup` | IgnoreExistingBackup is true iff the BACKUP schedule should still be created even if a backup is already present in its destination. | no | +| `ApplicationName` | The application name for the session where recovery event was created. | no | +| `NumRows` | NumRows is the number of rows successfully imported, backed up or restored. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `sampled_exec_stats` + +An event of type `sampled_exec_stats` contains execution statistics that apply to both statements +and transactions. These stats as a whole are collected using a sampling approach. +These exec stats are meant to contain the same fields as ExecStats in +apps_stats.proto but are for a single execution rather than aggregated executions. +Fields in this struct should be updated in sync with apps_stats.proto. + + +| Field | Description | Sensitive | +|--|--|--| +| `NetworkBytes` | NetworkBytes collects the number of bytes sent over the network by DistSQL components. | no | +| `MaxMemUsage` | MaxMemUsage collects the maximum memory usage that occurred on a node. | no | +| `ContentionTime` | ContentionTime collects the time in seconds statements in the transaction spent contending. | no | +| `NetworkMessages` | NetworkMessages collects the number of messages that were sent over the network by DistSQL components. | no | +| `MaxDiskUsage` | MaxDiskUsage collects the maximum temporary disk usage that occurred. This is set in cases where a query had to spill to disk, e.g. when performing a large sort where not all of the tuples fit in memory. | no | +| `CPUSQLNanos` | CPUSQLNanos collects the CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `MVCCIteratorStats` | Internal storage iteration statistics. | yes | + + + +### `sampled_query` + +An event of type `sampled_query` is the SQL query event logged to the telemetry channel. It +contains common SQL event/execution details. + + +| Field | Description | Sensitive | +|--|--|--| +| `SkippedQueries` | skipped_queries indicate how many SQL statements were not considered for sampling prior to this one. If the field is omitted, or its value is zero, this indicates that no statement was omitted since the last event. | no | +| `CostEstimate` | Cost of the query as estimated by the optimizer. | no | +| `Distribution` | The distribution of the DistSQL query plan (local, full, or partial). | no | +| `PlanGist` | The query's plan gist bytes as a base64 encoded string. | no | +| `SessionID` | SessionID is the ID of the session that initiated the query. | no | +| `Database` | Name of the database that initiated the query. | no | +| `StatementID` | Statement ID of the query. | no | +| `TransactionID` | Transaction ID of the query. | no | +| `MaxFullScanRowsEstimate` | Maximum number of rows scanned by a full scan, as estimated by the optimizer. | no | +| `TotalScanRowsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer. | no | +| `OutputRowsEstimate` | The number of rows output by the query, as estimated by the optimizer. | no | +| `StatsAvailable` | Whether table statistics were available to the optimizer when planning the query. | no | +| `NanosSinceStatsCollected` | The maximum number of nanoseconds that have passed since stats were collected on any table scanned by this query. | no | +| `BytesRead` | The number of bytes read from disk. | no | +| `RowsRead` | The number of rows read from disk. | no | +| `RowsWritten` | The number of rows written. | no | +| `InnerJoinCount` | The number of inner joins in the query plan. | no | +| `LeftOuterJoinCount` | The number of left (or right) outer joins in the query plan. | no | +| `FullOuterJoinCount` | The number of full outer joins in the query plan. | no | +| `SemiJoinCount` | The number of semi joins in the query plan. | no | +| `AntiJoinCount` | The number of anti joins in the query plan. | no | +| `IntersectAllJoinCount` | The number of intersect all joins in the query plan. | no | +| `ExceptAllJoinCount` | The number of except all joins in the query plan. | no | +| `HashJoinCount` | The number of hash joins in the query plan. | no | +| `CrossJoinCount` | The number of cross joins in the query plan. | no | +| `IndexJoinCount` | The number of index joins in the query plan. | no | +| `LookupJoinCount` | The number of lookup joins in the query plan. | no | +| `MergeJoinCount` | The number of merge joins in the query plan. | no | +| `InvertedJoinCount` | The number of inverted joins in the query plan. | no | +| `ApplyJoinCount` | The number of apply joins in the query plan. | no | +| `ZigZagJoinCount` | The number of zig zag joins in the query plan. | no | +| `ContentionNanos` | The duration of time in nanoseconds that the query experienced contention. | no | +| `Regions` | The regions of the nodes where SQL processors ran. | no | +| `NetworkBytesSent` | The number of network bytes by DistSQL components. | no | +| `MaxMemUsage` | The maximum amount of memory usage by nodes for this query. | no | +| `MaxDiskUsage` | The maximum amount of disk usage by nodes for this query. | no | +| `KVBytesRead` | The number of bytes read at the KV layer for this query. | no | +| `KVPairsRead` | The number of key-value pairs read at the KV layer for this query. | no | +| `KVRowsRead` | The number of rows read at the KV layer for this query. | no | +| `NetworkMessages` | The number of network messages sent by nodes for this query by DistSQL components. | no | +| `IndexRecommendations` | Generated index recommendations for this query. | no | +| `ScanCount` | The number of scans in the query plan. | no | +| `ScanWithStatsCount` | The number of scans using statistics (including forecasted statistics) in the query plan. | no | +| `ScanWithStatsForecastCount` | The number of scans using forecasted statistics in the query plan. | no | +| `TotalScanRowsWithoutForecastsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer without using forecasts. | no | +| `NanosSinceStatsForecasted` | The greatest quantity of nanoseconds that have passed since the forecast time (or until the forecast time, if it is in the future, in which case it will be negative) for any table with forecasted stats scanned by this query. | no | +| `Indexes` | The list of indexes used by this query. | no | +| `CpuTimeNanos` | Collects the cumulative CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `KvGrpcCalls` | The number of grpc calls done to get data form KV nodes | no | +| `KvTimeNanos` | Cumulated time spent waiting for a KV request. This includes disk IO time and potentially network time (if any of the keys are not local). | no | +| `ServiceLatencyNanos` | The time to service the query, from start of parse to end of execute. | no | +| `OverheadLatencyNanos` | The difference between service latency and the sum of parse latency + plan latency + run latency . | no | +| `RunLatencyNanos` | The time to run the query and fetch or compute the result rows. | no | +| `PlanLatencyNanos` | The time to transform the AST into a logical query plan. | no | +| `IdleLatencyNanos` | The time between statement executions in a transaction | no | +| `ParseLatencyNanos` | The time to transform the SQL string into an abstract syntax tree (AST). | no | +| `MvccStepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccStepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccBlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `MvccBlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `MvccKeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `SchemaChangerMode` | SchemaChangerMode is the mode that was used to execute the schema change, if any. | no | +| `SQLInstanceIDs` | SQLInstanceIDs is a list of all the SQL instances used in this statement's execution. | no | +| `KVNodeIDs` | KVNodeIDs is a list of all the KV nodes used in this statement's execution. | no | +| `StatementFingerprintID` | Statement fingerprint ID of the query. | no | +| `UsedFollowerRead` | UsedFollowerRead indicates whether at least some reads were served by the follower replicas. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sampled_transaction` + +An event of type `sampled_transaction` is the event logged to telemetry at the end of transaction execution. + + +| Field | Description | Sensitive | +|--|--|--| +| `User` | User is the user account that triggered the transaction. The special usernames `root` and `node` are not considered sensitive. | depends | +| `ApplicationName` | ApplicationName is the application name for the session where the transaction was executed. This is included in the event to ease filtering of logging output by application. | no | +| `TxnCounter` | TxnCounter is the sequence number of the SQL transaction inside its session. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `TransactionID` | TransactionID is the id of the transaction. | no | +| `Committed` | Committed indicates if the transaction committed successfully. We want to include this value even if it is false. | no | +| `ImplicitTxn` | ImplicitTxn indicates if the transaction was an implicit one. We want to include this value even if it is false. | no | +| `StartTimeUnixNanos` | StartTimeUnixNanos is the time the transaction was started. Expressed as unix time in nanoseconds. | no | +| `EndTimeUnixNanos` | EndTimeUnixNanos the time the transaction finished (either committed or aborted). Expressed as unix time in nanoseconds. | no | +| `ServiceLatNanos` | ServiceLatNanos is the time to service the whole transaction, from start to end of execution. | no | +| `SQLSTATE` | SQLSTATE is the SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | ErrorText is the text of the error if any. | partially | +| `NumRetries` | NumRetries is the number of time when the txn was retried automatically by the server. | no | +| `LastAutoRetryReason` | LastAutoRetryReason is a string containing the reason for the last automatic retry. | partially | +| `NumRows` | NumRows is the total number of rows returned across all statements. | no | +| `RetryLatNanos` | RetryLatNanos is the amount of time spent retrying the transaction. | no | +| `CommitLatNanos` | CommitLatNanos is the amount of time spent committing the transaction after all statement operations. | no | +| `IdleLatNanos` | IdleLatNanos is the amount of time spent waiting for the client to send statements while the transaction is open. | no | +| `BytesRead` | BytesRead is the number of bytes read from disk. | no | +| `RowsRead` | RowsRead is the number of rows read from disk. | no | +| `RowsWritten` | RowsWritten is the number of rows written to disk. | no | +| `SampledExecStats` | SampledExecStats is a nested field containing execution statistics. This field will be omitted if the stats were not sampled. | yes | +| `SkippedTransactions` | SkippedTransactions is the number of transactions that were skipped as part of sampling prior to this one. We only count skipped transactions when telemetry logging is enabled and the sampling mode is set to "transaction". | no | +| `TransactionFingerprintID` | TransactionFingerprintID is the fingerprint ID of the transaction. This can be used to find the transaction in the console. | no | +| `StatementFingerprintIDs` | StatementFingerprintIDs is an array of statement fingerprint IDs belonging to this transaction. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_descriptor` + +An event of type `schema_descriptor` is an event for schema telemetry, whose purpose is +to take periodic snapshots of the cluster's SQL schema and publish them in +the telemetry log channel. For all intents and purposes, the data in such a +snapshot can be thought of the outer join of certain system tables: +namespace, descriptor, and at some point perhaps zones, etc. + +Snapshots are too large to conveniently be published as a single log event, +so instead they're broken down into SchemaDescriptor events which +contain the data in one record of this outer join projection. These events +are prefixed by a header (a SchemaSnapshotMetadata event). + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of the snapshot that this event is part of. | no | +| `ParentDatabaseID` | ParentDatabaseID matches the same key column in system.namespace. | no | +| `ParentSchemaID` | ParentSchemaID matches the same key column in system.namespace. | no | +| `Name` | Name matches the same key column in system.namespace. | no | +| `DescID` | DescID matches the 'id' column in system.namespace and system.descriptor. | no | +| `Desc` | Desc matches the 'descriptor' column in system.descriptor. Some contents of the descriptor may be redacted to prevent leaking PII. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_snapshot_metadata` + +An event of type `schema_snapshot_metadata` is an event describing a schema snapshot, which +is a set of SchemaDescriptor messages sharing the same SnapshotID. + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of this snapshot. | no | +| `NumRecords` | NumRecords is how many SchemaDescriptor events are in the snapshot. | no | +| `AsOfTimestamp` | AsOfTimestamp is when the snapshot was taken. This is equivalent to the timestamp given in the AS OF SYSTEM TIME clause when querying the namespace and descriptor tables in the system database. Expressed as nanoseconds since the Unix epoch. | no | +| `Errors` | Errors records any errors encountered when post-processing this snapshot, which includes the redaction of any potential PII. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Zone config events + +Events in this category pertain to zone configuration changes on +the SQL schema or system ranges. + +When zone configs apply to individual tables or other objects in a +SQL logical schema, they are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these zone config events are preserved +in each tenant's own `system.eventlog` table. + +When they apply to cluster-level ranges (e.g., the system zone config), +they are stored in the system tenant's own `system.eventlog` table. + +Events in this category are logged to the `OPS` channel. + + +### `remove_zone_config` + +An event of type `remove_zone_config` is recorded when a zone config is removed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `set_zone_config` + +An event of type `set_zone_config` is recorded when a zone config is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `ResolvedOldConfig` | The string representation of the resolved old zone config. This is not necessarily the same as the zone config that was previously set -- as it includes the resolved values of the zone config options. In other words, a zone config that hasn't been properly "set" yet (and inherits from its parent) will have a resolved_old_config that has details of the values it inherits from its parent. This is particularly useful to get a proper diff between the old and new zone config. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + + + + +## Enumeration types + +### `AuthFailReason` + +AuthFailReason is the inventory of possible reasons for an +authentication failure. + + +| Value | Textual alias in code or documentation | Description | +|--|--|--| +| 0 | UNKNOWN | is reported when the reason is unknown. | +| 1 | USER_RETRIEVAL_ERROR | occurs when there was an internal error accessing the principals. | +| 2 | USER_NOT_FOUND | occurs when the principal is unknown. | +| 3 | LOGIN_DISABLED | occurs when the user does not have LOGIN privileges. | +| 4 | METHOD_NOT_FOUND | occurs when no HBA rule matches or the method does not exist. | +| 5 | PRE_HOOK_ERROR | occurs when the authentication handshake encountered a protocol error. | +| 6 | CREDENTIALS_INVALID | occurs when the client-provided credentials were invalid. | +| 7 | CREDENTIALS_EXPIRED | occur when the credentials provided by the client are expired. | +| 8 | NO_REPLICATION_ROLEOPTION | occurs when the connection requires a replication role option, but the user does not have it. | +| 9 | AUTHORIZATION_ERROR | is used for errors during the authorization phase. For example, this would include issues with mapping LDAP groups to SQL roles and granting those roles to the user. | + + + diff --git a/src/current/_includes/cockroach-generated/release-25.2/logformats.md b/src/current/_includes/cockroach-generated/release-25.2/logformats.md new file mode 100644 index 00000000000..89580c9fc15 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.2/logformats.md @@ -0,0 +1,382 @@ + +The supported log output formats are documented below. + + +- [`crdb-v1`](#format-crdb-v1) + +- [`crdb-v1-count`](#format-crdb-v1-count) + +- [`crdb-v1-tty`](#format-crdb-v1-tty) + +- [`crdb-v1-tty-count`](#format-crdb-v1-tty-count) + +- [`crdb-v2`](#format-crdb-v2) + +- [`crdb-v2-tty`](#format-crdb-v2-tty) + +- [`json`](#format-json) + +- [`json-compact`](#format-json-compact) + +- [`json-fluent`](#format-json-fluent) + +- [`json-fluent-compact`](#format-json-fluent-compact) + + + +## Format `crdb-v1` + + +This is a legacy file format used from CockroachDB v1.0. + +Each log entry is emitted using a common prefix, described below, followed by: + +- The logging context tags enclosed between `[` and `]`, if any. It is possible + for this to be omitted if there were no context tags. +- Optionally, a counter column, if the option 'show-counter' is enabled. See below for details. +- the text of the log entry. + +Beware that the text of the log entry can span multiple lines. +The following caveats apply: + +- The text of the log entry can start with text enclosed between `[` and `]`. + If there were no logging tags to start with, it is not possible to distinguish between + logging context tag information and a `[...]` string in the main text of the + log entry. This means that this format is ambiguous. + + To remove this ambiguity, you can use the option 'show-counter'. + +- The text of the log entry can embed arbitrary application-level strings, + including strings that represent log entries. In particular, an accident + of implementation can cause the common entry prefix (described below) + to also appear on a line of its own, as part of the payload of a previous + log entry. There is no automated way to recognize when this occurs. + Care must be taken by a human observer to recognize these situations. + +- The log entry parser provided by CockroachDB to read log files is faulty + and is unable to recognize the aforementioned pitfall; nor can it read + entries larger than 64KiB successfully. Generally, use of this internal + log entry parser is discouraged for entries written with this format. + +See the newer format `crdb-v2` for an alternative +without these limitations. + +### Header lines + +At the beginning of each file, a header is printed using a similar format as +regular log entries. This header reports when the file was created, +which parameters were used to start the server, the server identifiers +if known, and other metadata about the running process. + +- This header appears to be logged at severity `INFO` (with an `I` prefix + at the start of the line) even though it does not really have a severity. +- The header is printed unconditionally even when a filter is configured to + omit entries at the `INFO` level. + +### Common log entry prefix + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker tags counter + +Reminder, the tags may be omitted; and the counter is only printed if the option +'show-counter' is specified. + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (omitted if zero for use by tests). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. | +| line | The line number where the entry originated. | +| marker | Redactability marker ` + redactableIndicator + ` (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. May be absent. | +| counter | The entry counter. Only included if 'show-counter' is enabled. | + +The redactability marker can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. + +If the marker ` + redactableIndicator + ` is present, the remainder of the log entry +contains delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `show-counter` | Whether to include the counter column in the line header. Without it, the format may be ambiguous due to the optionality of tags. | +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v1-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: none` + + +## Format `crdb-v1-tty` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: false` +- `colors: auto` + + +## Format `crdb-v1-tty-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: auto` + + +## Format `crdb-v2` + +This is the main file format used from CockroachDB v21.1. + +Each log entry is emitted using a common prefix, described below, +followed by the text of the log entry. + +### Entry format + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker [tags...] counter cont + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (zero when cannot be determined). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. Also see below. | +| line | The line number where the entry originated. | +| marker | Redactability marker "⋮" (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. See below. | +| counter | The optional entry counter (see below for details). | +| cont | Continuation mark for structured and multi-line entries. See below. | + +The `chan@` prefix before the file name indicates the logging channel, +and is omitted if the channel is `DEV`. + +The file name may be prefixed by the string `(gostd) ` to indicate +that the log entry was produced inside the Go standard library, instead +of a CockroachDB component. Entry parsers must be configured to ignore this prefix +when present. + +`marker` can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. +If the marker "⋮" is present, the remainder of the log entry +contains delimiters (‹...›) +around fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +when log redaction is requested. + +The logging `tags` are enclosed between square brackets `[...]`, +and the syntax `[-]` is used when there are no logging tags +associated with the log entry. + +`counter` is numeric, and is incremented for every +log entry emitted to this sink. (There is thus one counter sequence per +sink.) For entries that do not have a counter value +associated (e.g., header entries in file sinks), the counter position +in the common prefix is empty: `tags` is then +followed by two ASCII space characters, instead of one space; the `counter`, +and another space. The presence of the two ASCII spaces indicates +reliably that no counter was present. + +`cont` is a format/continuation indicator: + +| Continuation indicator | ASCII | Description | +|------------------------|-------|--| +| space | 0x32 | Start of an unstructured entry. | +| equal sign, "=" | 0x3d | Start of a structured entry. | +| exclamation mark, "!" | 0x21 | Start of an embedded stack trace. | +| plus sign, "+" | 0x2b | Continuation of a multi-line entry. The payload contains a newline character at this position. | +| vertical bar | 0x7c | Continuation of a large entry. | + +### Examples + +Example single-line unstructured entry: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 started with engine type ‹2› +~~~ + +Example multi-line unstructured entry: + +~~~ +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 node startup completed: +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 +CockroachDB node starting at 2021-01-16 21:49 (took 0.0s) +~~~ + +Example structured entry: + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventType":"node_restart"} +~~~ + +Example long entries broken up into multiple lines: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.... +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 |aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +~~~ + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventTy... +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 |pe":"node_restart"} +~~~ + +### Backward-compatibility notes + +Entries in this format can be read by most `crdb-v1` log parsers, +in particular the one included in the DB console and +also the [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +facility. + +However, implementers of previous version parsers must +understand that the logging tags field is now always +included, and the lack of logging tags is included +by a tag string set to `[-]`. + +Likewise, the entry counter is now also always included, +and there is a special character after `counter` +to indicate whether the remainder of the line is a +structured entry, or a continuation of a previous entry. + +Finally, in the previous format, structured entries +were prefixed with the string `Structured entry: `. In +the new format, they are prefixed by the `=` continuation +indicator. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v2-tty` + +This format name is an alias for 'crdb-v2' with +the following format option defaults: + +- `colors: auto` + + +## Format `json` + +This format emits log entries as a JSON payload. + +The JSON object is guaranteed to not contain unescaped newlines +or other special characters, and the entry as a whole is followed +by a newline character. This makes the format suitable for +processing over a stream unambiguously. + +Each entry contains at least the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `tag` | `tag` | (Only if the option `fluent-tag: true` is given.) A Fluent tag for the event, formed by the process name and the logging channel. | +| `d` | `datetime` | The pretty-printed date/time of the event timestamp, if enabled via options. | +| `f` | `file` | The name of the source file where the event was emitted. | +| `g` | `goroutine` | The identifier of the goroutine where the event was emitted. | +| `l` | `line` | The line number where the event was emitted in the source. | +| `r` | `redactable` | Whether the payload is redactable (see below for details). | +| `t` | `timestamp` | The timestamp at which the event was emitted on the logging channel. | +| `v` | `version` | The binary version with which the event was generated. | + + +After a couple of *header* entries written at the beginning of each log sink, +all subsequent log entries also contain the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `C` | `channel` | The name of the logging channel where the event was sent. | +| `sev` | `severity` | The severity of the event. | +| `c` | `channel_numeric` | The numeric identifier for the logging channel where the event was sent. | +| `n` | `entry_counter` | The entry number on this logging sink, relative to the last process restart. | +| `s` | `severity_numeric` | The numeric value of the severity of the event. | + + +Additionally, the following fields are conditionally present: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `N` | `node_id` | The node ID where the event was generated, once known. Only reported for single-tenant or KV servers. | +| `x` | `cluster_id` | The cluster ID where the event was generated, once known. Only reported for single-tenant of KV servers. | +| `q` | `instance_id` | The SQL instance ID where the event was generated, once known. | +| `T` | `tenant_id` | The SQL tenant ID where the event was generated, once known. | +| `V` | `tenant_name` | The SQL virtual cluster where the event was generated, once known. | +| `tags` | `tags` | The logging context tags for the entry, if there were context tags. | +| `message` | `message` | For unstructured events, the flat text payload. | +| `event` | `event` | The logging event, if structured (see below for details). | +| `stacks` | `stacks` | Goroutine stacks, for fatal events. | + +When an entry is structured, the `event` field maps to a dictionary +whose structure is one of the documented structured events. See the [reference documentation](eventlog.html) +for structured events for a list of possible payloads. + +When the entry is marked as `redactable`, the `tags`, `message`, and/or `event` payloads +contain delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `datetime-format` | The format to use for the `datetime` field. The value can be one of `none`, `iso8601`/`rfc3339` (synonyms), or `rfc1123`. Default is `none`. | +| `datetime-timezone` | The timezone to use for the `datetime` field. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | +| `tag-style` | The tags to include in the envelope. The value can be `compact` (one letter tags) or `verbose` (long-form tags). Default is `verbose`. | +| `fluent-tag` | Whether to produce an additional field called `tag` for Fluent compatibility. Default is `false`. | + + + +## Format `json-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: false` +- `tag-style: compact` + + +## Format `json-fluent` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: verbose` + + +## Format `json-fluent-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: compact` + + diff --git a/src/current/_includes/cockroach-generated/release-25.2/logging.md b/src/current/_includes/cockroach-generated/release-25.2/logging.md new file mode 100644 index 00000000000..8b628dc2dd9 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.2/logging.md @@ -0,0 +1,179 @@ +## Logging levels (severities) + +### INFO + +The `INFO` severity is used for informational messages that do not +require action. + +### WARNING + +The `WARNING` severity is used for situations which may require special handling, +where normal operation is expected to resume automatically. + +### ERROR + +The `ERROR` severity is used for situations that require special handling, +where normal operation could not proceed as expected. +Other operations can continue mostly unaffected. + +### FATAL + +The `FATAL` severity is used for situations that require an immedate, hard +server shutdown. A report is also sent to telemetry if telemetry +is enabled. + + +## Logging channels + +### `DEV` + +The `DEV` channel is used during development to collect log +details useful for troubleshooting that fall outside the +scope of other channels. It is also the default logging +channel for events not associated with a channel. + +This channel is special in that there are no constraints as to +what may or may not be logged on it. Conversely, users in +production deployments are invited to not collect `DEV` logs in +centralized logging facilities, because they likely contain +sensitive operational data. +See [Configure logs](configure-logs.html#dev-channel). + +### `OPS` + +The `OPS` channel is used to report "point" operational events, +initiated by user operators or automation: + + - Operator or system actions on server processes: process starts, + stops, shutdowns, crashes (if they can be logged), + including each time: command-line parameters, current version being run + - Actions that impact the topology of a cluster: node additions, + removals, decommissions, etc. + - Job-related initiation or termination + - [Cluster setting](cluster-settings.html) changes + - [Zone configuration](configure-replication-zones.html) changes + +### `HEALTH` + +The `HEALTH` channel is used to report "background" operational +events, initiated by CockroachDB or reporting on automatic processes: + + - Current resource usage, including critical resource usage + - Node-node connection events, including connection errors and + gossip details + - Range and table leasing events + - Up- and down-replication, range unavailability + +### `STORAGE` + +The `STORAGE` channel is used to report low-level storage +layer events (RocksDB/Pebble). + +### `SESSIONS` + +The `SESSIONS` channel is used to report client network activity when enabled via +the `server.auth_log.sql_connections.enabled` and/or +`server.auth_log.sql_sessions.enabled` [cluster setting](cluster-settings.html): + + - Connections opened/closed + - Authentication events: logins, failed attempts + - Session and query cancellation + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_SCHEMA` + +The `SQL_SCHEMA` channel is used to report changes to the +SQL logical schema, excluding privilege and ownership changes +(which are reported separately on the `PRIVILEGES` channel) and +zone configuration changes (which go to the `OPS` channel). + +This includes: + + - Database/schema/table/sequence/view/type creation + - Adding/removing/changing table columns + - Changing sequence parameters + +`SQL_SCHEMA` events generally comprise changes to the schema that affect the +functional behavior of client apps using stored objects. + +### `USER_ADMIN` + +The `USER_ADMIN` channel is used to report changes +in users and roles, including: + + - Users added/dropped + - Changes to authentication credentials (e.g., passwords, validity, etc.) + - Role grants/revocations + - Role option grants/revocations + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `PRIVILEGES` + +The `PRIVILEGES` channel is used to report data +authorization changes, including: + + - Privilege grants/revocations on database, objects, etc. + - Object ownership changes + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SENSITIVE_ACCESS` + +The `SENSITIVE_ACCESS` channel is used to report SQL +data access to sensitive data: + + - Data access audit events (when table audit is enabled via + [ALTER TABLE ... EXPERIMENTAL_AUDIT](alter-table.html#experimental_audit)) + - Data access audit events (when role-based audit is enabled via + [`sql.log.user_audit` cluster setting](role-based-audit-logging.html#syntax-of-audit-settings)) + - SQL statements executed by users with the admin role + - Operations that write to system tables + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_EXEC` + +The `SQL_EXEC` channel is used to report SQL execution on +behalf of client connections: + + - Logical SQL statement executions (when enabled via the + `sql.log.all_statements.enabled` [cluster setting](cluster-settings.html)) + - uncaught Go panic errors during the execution of a SQL statement. + +### `SQL_PERF` + +The `SQL_PERF` channel is used to report SQL executions +that are marked as "out of the ordinary" +to facilitate performance investigations. +This includes the SQL "slow query log". + +Arguably, this channel overlaps with `SQL_EXEC`. +However, we keep both channels separate for backward compatibility +with versions prior to v21.1, where the corresponding events +were redirected to separate files. + +### `SQL_INTERNAL_PERF` + +The `SQL_INTERNAL_PERF` channel is like the `SQL_PERF` channel, but is aimed at +helping developers of CockroachDB itself. It exists as a separate +channel so as to not pollute the `SQL_PERF` logging output with +internal troubleshooting details. + +### `TELEMETRY` + +The `TELEMETRY` channel reports telemetry events. Telemetry events describe +feature usage within CockroachDB and anonymizes any application- +specific data. + +### `KV_DISTRIBUTION` + +The `KV_DISTRIBUTION` channel is used to report data distribution events, such as moving +replicas between stores in the cluster, or adding (removing) replicas to +ranges. + diff --git a/src/current/_includes/cockroach-generated/release-25.2/settings/settings.html b/src/current/_includes/cockroach-generated/release-25.2/settings/settings.html new file mode 100644 index 00000000000..92e53189ec5 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.2/settings/settings.html @@ -0,0 +1,383 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingTypeDefaultDescriptionSupported Deployments
admission.disk_bandwidth_tokens.elastic.enabled
booleantruewhen true, and provisioned bandwidth for the disk corresponding to a store is configured, tokens for elastic work will be limited if disk bandwidth becomes a bottleneckDedicated/Self-Hosted
admission.epoch_lifo.enabled
booleanfalsewhen true, epoch-LIFO behavior is enabled when there is significant delay in admissionServerless/Dedicated/Self-Hosted
admission.epoch_lifo.epoch_closing_delta_duration
duration5msthe delta duration before closing an epoch, for epoch-LIFO admission control orderingServerless/Dedicated/Self-Hosted
admission.epoch_lifo.epoch_duration
duration100msthe duration of an epoch, for epoch-LIFO admission control orderingServerless/Dedicated/Self-Hosted
admission.epoch_lifo.queue_delay_threshold_to_switch_to_lifo
duration105msthe queue delay encountered by a (tenant,priority) for switching to epoch-LIFO orderingServerless/Dedicated/Self-Hosted
admission.kv.enabled
booleantruewhen true, work performed by the KV layer is subject to admission controlDedicated/Self-Hosted
admission.sql_kv_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a KV response is subject to admission controlServerless/Dedicated/Self-Hosted
admission.sql_sql_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a DistSQL response is subject to admission controlServerless/Dedicated/Self-Hosted
bulkio.backup.deprecated_full_backup_with_subdir.enabled
booleanfalsewhen true, a backup command with a user specified subdirectory will create a full backup at the subdirectory if no backup already exists at that subdirectoryServerless/Dedicated/Self-Hosted
bulkio.backup.file_size
byte size128 MiBtarget size for individual data files produced during BACKUPServerless/Dedicated/Self-Hosted
bulkio.backup.read_timeout
duration5m0samount of time after which a read attempt is considered timed out, which causes the backup to failServerless/Dedicated/Self-Hosted
bulkio.backup.read_with_priority_after
duration1m0samount of time since the read-as-of time above which a BACKUP should use priority when retrying readsServerless/Dedicated/Self-Hosted
physical_replication.consumer.minimum_flush_interval
(alias: bulkio.stream_ingestion.minimum_flush_interval)
duration5sthe minimum timestamp between flushes; flushes may still occur if internal buffers fill upDedicated/Self-Hosted
changefeed.aggregator.flush_jitter
float0.1jitter aggregator flushes as a fraction of min_checkpoint_frequency. This setting has no effect if min_checkpoint_frequency is set to 0.Serverless/Dedicated/Self-Hosted
changefeed.backfill.concurrent_scan_requests
integer0number of concurrent scan requests per node issued during a backfillServerless/Dedicated/Self-Hosted
changefeed.backfill.scan_request_size
integer524288the maximum number of bytes returned by each scan requestServerless/Dedicated/Self-Hosted
changefeed.batch_reduction_retry.enabled
(alias: changefeed.batch_reduction_retry_enabled)
booleanfalseif true, kafka changefeeds upon erroring on an oversized batch will attempt to resend the messages with progressively lower batch sizesServerless/Dedicated/Self-Hosted
changefeed.default_range_distribution_strategy
enumerationdefaultconfigures how work is distributed among nodes for a given changefeed. for the most balanced distribution, use `balanced_simple`. changing this setting will not override locality restrictions [default = 0, balanced_simple = 1]Serverless/Dedicated/Self-Hosted
changefeed.event_consumer_worker_queue_size
integer16if changefeed.event_consumer_workers is enabled, this setting sets the maxmimum number of events which a worker can bufferServerless/Dedicated/Self-Hosted
changefeed.event_consumer_workers
integer0the number of workers to use when processing events: <0 disables, 0 assigns a reasonable default, >0 assigns the setting value. for experimental/core changefeeds and changefeeds using parquet format, this is disabledServerless/Dedicated/Self-Hosted
changefeed.fast_gzip.enabled
booleantrueuse fast gzip implementationServerless/Dedicated/Self-Hosted
changefeed.span_checkpoint.lag_threshold
(alias: changefeed.frontier_highwater_lag_checkpoint_threshold)
duration10m0sthe amount of time a changefeed's lagging (slowest) spans must lag behind its leading (fastest) spans before a span-level checkpoint to save leading span progress is written; if 0, span-level checkpoints due to lagging spans is disabledServerless/Dedicated/Self-Hosted
changefeed.kafka.max_request_size
byte size256 MiBthe maximum number of uncompressed bytes sent in a single request to a Kafka broker; lowering this value helps avoid spurious "message too large" errors that can occur when multiple messages are combined into a single batch; this setting is overridden by the per-changefeed Flush { MaxBytes: <int> } optionServerless/Dedicated/Self-Hosted
changefeed.kafka_v2_error_details.enabled
booleantrueif enabled, Kafka v2 sinks will include the message key, size, and MVCC timestamp in message too large errorsServerless/Dedicated/Self-Hosted
changefeed.memory.per_changefeed_limit
byte size512 MiBcontrols amount of data that can be buffered per changefeedServerless/Dedicated/Self-Hosted
changefeed.resolved_timestamp.min_update_interval
(alias: changefeed.min_highwater_advance)
duration0sminimum amount of time that must have elapsed since the last time a changefeed's resolved timestamp was updated before it is eligible to be updated again; default of 0 means no minimum interval is enforced but updating will still be limited by the average time it takes to checkpoint progressServerless/Dedicated/Self-Hosted
changefeed.node_throttle_config
stringspecifies node level throttling configuration for all changefeeedsServerless/Dedicated/Self-Hosted
changefeed.partition_alg.enabled
booleanfalseif enabled, allows specifying the partition_alg changefeed option to choose between fnv-1a (default) and murmur2 hash functions for Kafka partitioning. Only affects changefeeds using a kafka sink with changefeed.new_kafka_sink_enabled set to true.Serverless/Dedicated/Self-Hosted
changefeed.protect_timestamp.max_age
duration96h0m0sfail the changefeed if the protected timestamp age exceeds this threshold; 0 disables expirationServerless/Dedicated/Self-Hosted
changefeed.protect_timestamp_interval
duration10m0scontrols how often the changefeed forwards its protected timestamp to the resolved timestampServerless/Dedicated/Self-Hosted
changefeed.schema_feed.read_with_priority_after
duration1m0sretry with high priority if we were not able to read descriptors for too long; 0 disablesServerless/Dedicated/Self-Hosted
changefeed.sink_io_workers
integer0the number of workers used by changefeeds when sending requests to the sink (currently the batching versions of webhook, pubsub, and kafka sinks that are enabled by changefeed.new_<sink type>_sink_enabled only): <0 disables, 0 assigns a reasonable default, >0 assigns the setting valueServerless/Dedicated/Self-Hosted
cloudstorage.azure.concurrent_upload_buffers
integer1controls the number of concurrent buffers that will be used by the Azure client when uploading chunks.Each buffer can buffer up to cloudstorage.write_chunk.size of memory during an uploadServerless/Dedicated/Self-Hosted
cloudstorage.azure.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.azure.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.azure.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.azure.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.gs.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.gs.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.gs.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.gs.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.http.custom_ca
stringcustom root CA (appended to system's default CAs) for verifying certificates when interacting with HTTPS storageServerless/Dedicated/Self-Hosted
cloudstorage.http.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.http.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.http.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.http.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nodelocal.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nodelocal.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nodelocal.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nodelocal.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nullsink.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nullsink.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nullsink.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.nullsink.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.s3.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.s3.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.s3.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.s3.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.timeout
duration10m0sthe timeout for import/export storage operationsServerless/Dedicated/Self-Hosted
cloudstorage.userfile.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.userfile.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.userfile.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cloudstorage.userfile.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroServerless/Dedicated/Self-Hosted
cluster.auto_upgrade.enabled
booleantruedisable automatic cluster version upgrade until resetServerless/Dedicated/Self-Hosted
cluster.organization
stringorganization nameDedicated/Self-hosted (read-write); Serverless (read-only)
cluster.preserve_downgrade_option
stringdisable (automatic or manual) cluster version upgrade from the specified version until resetServerless/Dedicated/Self-Hosted
debug.zip.redact_addresses.enabled
booleanfalseenables the redaction of hostnames and ip addresses in debug zipServerless/Dedicated/Self-Hosted
diagnostics.active_query_dumps.enabled
booleantrueexperimental: enable dumping of anonymized active queries to disk when node is under memory pressureDedicated/Self-hosted (read-write); Serverless (read-only)
diagnostics.forced_sql_stat_reset.interval
duration2h0m0sinterval after which the reported SQL Stats are reset even if not collected by telemetry reporter. It has a max value of 24H.Serverless/Dedicated/Self-Hosted
diagnostics.memory_monitoring_dumps.enabled
booleantrueenable dumping of memory monitoring state at the same time as heap profiles are takenDedicated/Self-hosted (read-write); Serverless (read-only)
diagnostics.reporting.enabled
booleantrueenable reporting diagnostic metrics to cockroach labs, but is ignored for Trial or Free licensesServerless/Dedicated/Self-Hosted
diagnostics.reporting.interval
duration1h0m0sinterval at which diagnostics data should be reportedServerless/Dedicated/Self-Hosted
enterprise.license
stringthe encoded cluster licenseDedicated/Self-hosted (read-write); Serverless (read-only)
external.graphite.endpoint
stringif nonempty, push server metrics to the Graphite or Carbon server at the specified host:portServerless/Dedicated/Self-Hosted
external.graphite.interval
duration10sthe interval at which metrics are pushed to Graphite (if enabled)Serverless/Dedicated/Self-Hosted
feature.backup.enabled
booleantrueset to true to enable backups, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.changefeed.enabled
booleantrueset to true to enable changefeeds, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.export.enabled
booleantrueset to true to enable exports, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.import.enabled
booleantrueset to true to enable imports, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.restore.enabled
booleantrueset to true to enable restore, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.schema_change.enabled
booleantrueset to true to enable schema changes, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.stats.enabled
booleantrueset to true to enable CREATE STATISTICS/ANALYZE, false to disable; default is trueServerless/Dedicated/Self-Hosted
feature.vector_index.enabled
booleanfalseset to true to enable vector indexes, false to disable; default is falseServerless/Dedicated/Self-Hosted
jobs.retention_time
duration336h0m0sthe amount of time for which records for completed jobs are retainedServerless/Dedicated/Self-Hosted
kv.allocator.lease_rebalance_threshold
float0.05minimum fraction away from the mean a store's lease count can be before it is considered for lease-transfersDedicated/Self-Hosted
kv.allocator.load_based_lease_rebalancing.enabled
booleantrueset to enable rebalancing of range leases based on load and latencyDedicated/Self-Hosted
kv.allocator.load_based_rebalancing
enumerationleases and replicaswhether to rebalance based on the distribution of load across stores [off = 0, leases = 1, leases and replicas = 2]Dedicated/Self-Hosted
kv.allocator.load_based_rebalancing.objective
enumerationcpuwhat objective does the cluster use to rebalance; if set to `qps` the cluster will attempt to balance qps among stores, if set to `cpu` the cluster will attempt to balance cpu usage among stores [qps = 0, cpu = 1]Dedicated/Self-Hosted
kv.allocator.load_based_rebalancing_interval
duration1m0sthe rough interval at which each store will check for load-based lease / replica rebalancing opportunitiesDedicated/Self-Hosted
kv.allocator.qps_rebalance_threshold
float0.1minimum fraction away from the mean a store's QPS (such as queries per second) can be before it is considered overfull or underfullDedicated/Self-Hosted
kv.allocator.range_rebalance_threshold
float0.05minimum fraction away from the mean a store's range count can be before it is considered overfull or underfullDedicated/Self-Hosted
kv.allocator.store_cpu_rebalance_threshold
float0.1minimum fraction away from the mean a store's cpu usage can be before it is considered overfull or underfullDedicated/Self-Hosted
kv.bulk_io_write.max_rate
byte size1.0 TiBthe rate limit (bytes/sec) to use for writes to disk on behalf of bulk io opsDedicated/Self-Hosted
kv.bulk_io_write.min_capacity_remaining_fraction
float0.05remaining store capacity fraction below which bulk ingestion requests are rejectedDedicated/Self-Hosted
kv.bulk_sst.max_allowed_overage
byte size64 MiBif positive, allowed size in excess of target size for SSTs from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryDedicated/Self-Hosted
kv.bulk_sst.target_size
byte size16 MiBtarget size for SSTs emitted from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryDedicated/Self-hosted (read-write); Serverless (read-only)
kv.closed_timestamp.follower_reads.enabled
(alias: kv.closed_timestamp.follower_reads_enabled)
booleantrueallow (all) replicas to serve consistent historical reads based on closed timestamp informationDedicated/Self-hosted (read-write); Serverless (read-only)
kv.closed_timestamp.lead_for_global_reads_auto_tune.enabled
booleanfalseif enabled, observed network latency between leaseholders and their furthest follower will be used to adjust closed timestamp policies for rangesranges configured to serve global reads. kv.closed_timestamp.lead_for_global_reads_override takes precedence if set.Dedicated/Self-hosted (read-write); Serverless (read-only)
kv.closed_timestamp.lead_for_global_reads_override
duration0sif nonzero, overrides the lead time that global_read ranges use to publish closed timestampsDedicated/Self-hosted (read-write); Serverless (read-only)
kv.closed_timestamp.side_transport_interval
duration200msthe interval at which the closed timestamp side-transport attempts to advance each range's closed timestamp; set to 0 to disable the side-transportDedicated/Self-hosted (read-write); Serverless (read-only)
kv.closed_timestamp.target_duration
duration3sif nonzero, attempt to provide closed timestamp notifications for timestamps trailing cluster time by approximately this durationDedicated/Self-hosted (read-write); Serverless (read-only)
kv.dist_sender.circuit_breaker.cancellation.enabled
booleantruewhen enabled, in-flight requests will be cancelled when the circuit breaker tripsServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.cancellation.write_grace_period
duration10show long after the circuit breaker trips to cancel write requests (these can't retry internally, so should be long enough to allow quorum/lease recovery)Serverless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.probe.interval
duration3sinterval between replica probesServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.probe.threshold
duration3sduration of errors or stalls after which a replica will be probedServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breaker.probe.timeout
duration3stimeout for replica probesServerless/Dedicated/Self-Hosted
kv.dist_sender.circuit_breakers.mode
enumerationliveness range onlyset of ranges to trip circuit breakers for failing or stalled replicas [no ranges = 0, liveness range only = 1, all ranges = 2]Serverless/Dedicated/Self-Hosted
kv.lease_transfer_read_summary.global_budget
byte size0 Bcontrols the maximum number of bytes that will be used to summarize the global segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Dedicated/Self-Hosted
kv.lease_transfer_read_summary.local_budget
byte size4.0 MiBcontrols the maximum number of bytes that will be used to summarize the local segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Dedicated/Self-Hosted
kv.log_range_and_node_events.enabled
booleantrueset to true to transactionally log range events (e.g., split, merge, add/remove voter/non-voter) into system.rangelogand node join and restart events into system.eventologDedicated/Self-Hosted
kv.protectedts.reconciliation.interval
duration5m0sthe frequency for reconciling jobs with protected timestamp recordsDedicated/Self-hosted (read-write); Serverless (read-only)
kv.raft.leader_fortification.fraction_enabled
float1controls the fraction of ranges for which the raft leader fortification protocol is enabled. Leader fortification is needed for a range to use a Leader lease. Set to 0.0 to disable leader fortification and, by extension, Leader leases. Set to 1.0 to enable leader fortification for all ranges and, by extension, use Leader leases for all ranges which do not require expiration-based leases. Set to a value between 0.0 and 1.0 to gradually roll out Leader leases across the ranges in a cluster.Dedicated/Self-Hosted
kv.range.range_size_hard_cap
byte size8.0 GiBhard cap on the maximum size a range is allowed to grow to withoutsplitting before writes to the range are blocked. Takes precedence over all other configurationsDedicated/Self-Hosted
kv.range_split.by_load.enabled
(alias: kv.range_split.by_load_enabled)
booleantrueallow automatic splits of ranges based on where load is concentratedDedicated/Self-Hosted
kv.range_split.load_cpu_threshold
duration500msthe CPU use per second over which, the range becomes a candidate for load based splittingDedicated/Self-Hosted
kv.range_split.load_qps_threshold
integer2500the QPS over which, the range becomes a candidate for load based splittingDedicated/Self-Hosted
kv.rangefeed.client.stream_startup_rate
integer100controls the rate per second the client will initiate new rangefeed stream for a single range; 0 implies unlimitedServerless/Dedicated/Self-Hosted
kv.rangefeed.closed_timestamp_refresh_interval
duration3sthe interval at which closed-timestamp updatesare delivered to rangefeeds; set to 0 to use kv.closed_timestamp.side_transport_intervalDedicated/Self-hosted (read-write); Serverless (read-only)
kv.rangefeed.enabled
booleanfalseif set, rangefeed registration is enabledDedicated/Self-hosted (read-write); Serverless (read-only)
kv.replica_circuit_breaker.slow_replication_threshold
duration1m0sduration after which slow proposals trip the per-Replica circuit breaker (zero duration disables breakers)Dedicated/Self-Hosted
kv.replica_raft.leaderless_unavailable_threshold
duration1m0sduration after which leaderless replicas is considered unavailable. Set to 0 to disable leaderless replica availability checksDedicated/Self-Hosted
kv.replica_stats.addsst_request_size_factor
integer50000the divisor that is applied to addsstable request sizes, then recorded in a leaseholders QPS; 0 means all requests are treated as cost 1Dedicated/Self-Hosted
kv.replication_reports.interval
duration1m0sthe frequency for generating the replication_constraint_stats, replication_stats_report and replication_critical_localities reports (set to 0 to disable)Dedicated/Self-Hosted
kv.snapshot_rebalance.max_rate
byte size32 MiBthe rate limit (bytes/sec) to use for rebalance and upreplication snapshotsDedicated/Self-Hosted
kv.transaction.max_intents_and_locks
integer0maximum count of inserts or durable locks for a single transactions, 0 to disableServerless/Dedicated/Self-Hosted
kv.transaction.max_intents_bytes
integer4194304maximum number of bytes used to track locks in transactionsServerless/Dedicated/Self-Hosted
kv.transaction.max_refresh_spans_bytes
integer4194304maximum number of bytes used to track refresh spans in serializable transactionsServerless/Dedicated/Self-Hosted
kv.transaction.randomized_anchor_key.enabled
booleanfalsedictates whether a transactions anchor key is randomized or notServerless/Dedicated/Self-Hosted
kv.transaction.reject_over_max_intents_budget.enabled
booleanfalseif set, transactions that exceed their lock tracking budget (kv.transaction.max_intents_bytes) are rejected instead of having their lock spans imprecisely compressedServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.locking_reads.enabled
booleantrueif enabled, transactional locking reads are pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.ranged_writes.enabled
booleantrueif enabled, transactional ranged writes are pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.enabled
(alias: kv.transaction.write_pipelining_enabled)
booleantrueif enabled, transactional writes are pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kv.transaction.write_pipelining.max_batch_size
(alias: kv.transaction.write_pipelining_max_batch_size)
integer128if non-zero, defines that maximum size batch that will be pipelined through Raft consensusServerless/Dedicated/Self-Hosted
kvadmission.store.provisioned_bandwidth
byte size0 Bif set to a non-zero value, this is used as the provisioned bandwidth (in bytes/s), for each store. It can be overridden on a per-store basis using the --store flag. Note that setting the provisioned bandwidth to a positive value may enable disk bandwidth based admission control, since admission.disk_bandwidth_tokens.elastic.enabled defaults to trueDedicated/Self-Hosted
kvadmission.store.snapshot_ingest_bandwidth_control.enabled
booleantrueif set to true, snapshot ingests will be subject to disk write control in ACDedicated/Self-Hosted
obs.tablemetadata.automatic_updates.enabled
booleanfalseenables automatic updates of the table metadata cache system.table_metadataServerless/Dedicated/Self-Hosted
obs.tablemetadata.data_valid_duration
duration20m0sthe duration for which the data in system.table_metadata is considered validServerless/Dedicated/Self-Hosted
schedules.backup.gc_protection.enabled
booleantrueenable chaining of GC protection across backups run as part of a scheduleServerless/Dedicated/Self-Hosted
security.client_cert.subject_required.enabled
booleanfalsemandates a requirement for subject role to be set for db userDedicated/Self-hosted (read-write); Serverless (read-only)
security.ocsp.mode
enumerationoffuse OCSP to check whether TLS certificates are revoked. If the OCSP server is unreachable, in strict mode all certificates will be rejected and in lax mode all certificates will be accepted. [off = 0, lax = 1, strict = 2]Serverless/Dedicated/Self-Hosted
security.ocsp.timeout
duration3stimeout before considering the OCSP server unreachableServerless/Dedicated/Self-Hosted
server.auth_log.sql_connections.enabled
booleanfalseif set, log SQL client connect and disconnect events to the SESSIONS log channel (note: may hinder performance on loaded nodes)Serverless/Dedicated/Self-Hosted
server.auth_log.sql_sessions.enabled
booleanfalseif set, log verbose SQL session authentication events to the SESSIONS log channel (note: may hinder performance on loaded nodes). Session start and end events are always logged regardless of this setting; disable the SESSIONS log channel to suppress them.Serverless/Dedicated/Self-Hosted
server.authentication_cache.enabled
booleantrueenables a cache used during authentication to avoid lookups to system tables when retrieving per-user authentication-related informationServerless/Dedicated/Self-Hosted
server.child_metrics.enabled
booleanfalseenables the exporting of child metrics, additional prometheus time series with extra labelsServerless/Dedicated/Self-Hosted
server.child_metrics.include_aggregate.enabled
booleantrueinclude the reporting of the aggregate time series when child metrics are enabled. This cluster setting has no effect if child metrics are disabled.Serverless/Dedicated/Self-Hosted
server.client_cert_expiration_cache.capacity
integer1000the maximum number of client cert expirations storedServerless/Dedicated/Self-Hosted
server.clock.forward_jump_check.enabled
(alias: server.clock.forward_jump_check_enabled)
booleanfalseif enabled, forward clock jumps > max_offset/2 will cause a panicServerless/Dedicated/Self-Hosted
server.clock.persist_upper_bound_interval
duration0sthe interval between persisting the wall time upper bound of the clock. The clock does not generate a wall time greater than the persisted timestamp and will panic if it sees a wall time greater than this value. When cockroach starts, it waits for the wall time to catch-up till this persisted timestamp. This guarantees monotonic wall time across server restarts. Not setting this or setting a value of 0 disables this feature.Serverless/Dedicated/Self-Hosted
server.consistency_check.max_rate
byte size8.0 MiBthe rate limit (bytes/sec) to use for consistency checks; used in conjunction with server.consistency_check.interval to control the frequency of consistency checks. Note that setting this too high can negatively impact performance.Dedicated/Self-Hosted
server.eventlog.enabled
booleantrueif set, logged notable events are also stored in the table system.eventlogServerless/Dedicated/Self-Hosted
server.eventlog.ttl
duration2160h0m0sif nonzero, entries in system.eventlog older than this duration are periodically purgedServerless/Dedicated/Self-Hosted
server.host_based_authentication.configuration
stringhost-based authentication configuration to use during connection authenticationServerless/Dedicated/Self-Hosted
server.hot_ranges_request.node.timeout
duration5m0sthe duration allowed for a single node to return hot range data before the request is cancelled; if set to 0, there is no timeoutServerless/Dedicated/Self-Hosted
server.hsts.enabled
booleanfalseif true, HSTS headers will be sent along with all HTTP requests. The headers will contain a max-age setting of one year. Browsers honoring the header will always use HTTPS to access the DB Console. Ensure that TLS is correctly configured prior to enabling.Serverless/Dedicated/Self-Hosted
server.http.base_path
string/path to redirect the user to upon succcessful loginServerless/Dedicated/Self-Hosted
server.identity_map.configuration
stringsystem-identity to database-username mappingsServerless/Dedicated/Self-Hosted
server.jwt_authentication.audience
stringsets accepted audience values for JWT logins over the SQL interfaceServerless/Dedicated/Self-Hosted
server.jwt_authentication.claim
stringsets the JWT claim that is parsed to get the usernameServerless/Dedicated/Self-Hosted
server.jwt_authentication.client.timeout
duration15ssets the client timeout for external calls made during JWT authentication (e.g. fetching JWKS, etc.)Serverless/Dedicated/Self-Hosted
server.jwt_authentication.enabled
booleanfalseenables or disables JWT login for the SQL interfaceServerless/Dedicated/Self-Hosted
server.jwt_authentication.issuers.configuration
(alias: server.jwt_authentication.issuers)
stringsets accepted issuer values for JWT logins over the SQL interface which can be a single issuer URL string or a JSON string containing an array of issuer URLs or a JSON object containing map of issuer URLS to JWKS URIsServerless/Dedicated/Self-Hosted
server.jwt_authentication.issuers.custom_ca
stringsets the PEM encoded custom root CA for verifying certificates while fetching JWKSServerless/Dedicated/Self-Hosted
server.jwt_authentication.jwks
string{"keys":[]}sets the public key set for JWT logins over the SQL interface (JWKS format)Serverless/Dedicated/Self-Hosted
server.jwt_authentication.jwks_auto_fetch.enabled
booleanfalseenables or disables automatic fetching of JWKS from the issuer's well-known endpoint or JWKS URI set in JWTAuthIssuersConfig. If this is enabled, the server.jwt_authentication.jwks will be ignored.Serverless/Dedicated/Self-Hosted
server.ldap_authentication.client.tls_certificate
stringsets the client certificate PEM for establishing mTLS connection with LDAP serverServerless/Dedicated/Self-Hosted
server.ldap_authentication.client.tls_key
stringsets the client key PEM for establishing mTLS connection with LDAP serverServerless/Dedicated/Self-Hosted
server.ldap_authentication.domain.custom_ca
stringsets the PEM encoded custom root CA for verifying domain certificates when establishing connection with LDAP serverServerless/Dedicated/Self-Hosted
server.log_gc.max_deletions_per_cycle
integer1000the maximum number of entries to delete on each purge of log-like system tablesServerless/Dedicated/Self-Hosted
server.log_gc.period
duration1h0m0sthe period at which log-like system tables are checked for old entriesServerless/Dedicated/Self-Hosted
server.max_connections_per_gateway
integer-1the maximum number of SQL connections per gateway allowed at a given time (note: this will only limit future connection attempts and will not affect already established connections). Negative values result in unlimited number of connections. Superusers are not affected by this limit.Serverless/Dedicated/Self-Hosted
server.max_open_transactions_per_gateway
integer-1the maximum number of open SQL transactions per gateway allowed at a given time. Negative values result in unlimited number of connections. Superusers are not affected by this limit.Serverless/Dedicated/Self-Hosted
server.oidc_authentication.autologin.enabled
(alias: server.oidc_authentication.autologin)
booleanfalseif true, logged-out visitors to the DB Console will be automatically redirected to the OIDC login endpointServerless/Dedicated/Self-Hosted
server.oidc_authentication.button_text
stringLog in with your OIDC providertext to show on button on DB Console login page to login with your OIDC provider (only shown if OIDC is enabled)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.claim_json_key
stringsets JSON key of principal to extract from payload after OIDC authentication completes (usually email or sid)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.client.timeout
duration15ssets the client timeout for external calls made during OIDC authentication (e.g. authorization code flow, etc.)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.client_id
stringsets OIDC client idServerless/Dedicated/Self-Hosted
server.oidc_authentication.client_secret
stringsets OIDC client secretServerless/Dedicated/Self-Hosted
server.oidc_authentication.enabled
booleanfalseenables or disabled OIDC login for the DB ConsoleServerless/Dedicated/Self-Hosted
server.oidc_authentication.principal_regex
string(.+)regular expression to apply to extracted principal (see claim_json_key setting) to translate to SQL user (golang regex format, must include 1 grouping to extract)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.provider.custom_ca
stringsets the PEM encoded custom root CA for verifying certificates while authenticating through the OIDC providerServerless/Dedicated/Self-Hosted
server.oidc_authentication.provider_url
stringsets OIDC provider URL ({provider_url}/.well-known/openid-configuration must resolve)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.redirect_url
stringhttps://localhost:8080/oidc/v1/callbacksets OIDC redirect URL via a URL string or a JSON string containing a required `redirect_urls` key with an object that maps from region keys to URL strings (URLs should point to your load balancer and must route to the path /oidc/v1/callback)Serverless/Dedicated/Self-Hosted
server.oidc_authentication.scopes
stringopenidsets OIDC scopes to include with authentication request (space delimited list of strings, required to start with `openid`)Serverless/Dedicated/Self-Hosted
server.rangelog.ttl
duration720h0m0sif nonzero, entries in system.rangelog older than this duration are periodically purgedDedicated/Self-Hosted
server.redact_sensitive_settings.enabled
booleanfalseenables or disables the redaction of sensitive settings in the output of SHOW CLUSTER SETTINGS and SHOW ALL CLUSTER SETTINGS for users without the MODIFYCLUSTERSETTING privilegeServerless/Dedicated/Self-Hosted
server.shutdown.connections.timeout
(alias: server.shutdown.connection_wait)
duration0sthe maximum amount of time a server waits for all SQL connections to be closed before proceeding with a drain. (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Serverless/Dedicated/Self-Hosted
server.shutdown.initial_wait
(alias: server.shutdown.drain_wait)
duration0sthe amount of time a server waits in an unready state before proceeding with a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting. --drain-wait is to specify the duration of the whole draining process, while server.shutdown.initial_wait is to set the wait time for health probes to notice that the node is not ready.)Serverless/Dedicated/Self-Hosted
server.shutdown.lease_transfer_iteration.timeout
(alias: server.shutdown.lease_transfer_wait)
duration5sthe timeout for a single iteration of the range lease transfer phase of draining (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Dedicated/Self-Hosted
server.shutdown.transactions.timeout
(alias: server.shutdown.query_wait)
duration10sthe timeout for waiting for active transactions to finish during a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Serverless/Dedicated/Self-Hosted
server.sql_tcp_keep_alive.count
integer3maximum number of probes that will be sent out before a connection is dropped because it's unresponsive (Linux and Darwin only)Serverless/Dedicated/Self-Hosted
server.sql_tcp_keep_alive.interval
duration10stime between keep alive probes and idle time before probes are sent outServerless/Dedicated/Self-Hosted
server.time_until_store_dead
duration5m0sthe time after which if there is no new gossiped information about a store, it is considered deadServerless/Dedicated/Self-Hosted
server.user_login.cert_password_method.auto_scram_promotion.enabled
booleantruewhether to automatically promote cert-password authentication to use SCRAMServerless/Dedicated/Self-Hosted
server.user_login.downgrade_scram_stored_passwords_to_bcrypt.enabled
booleantrueif server.user_login.password_encryption=crdb-bcrypt, this controls whether to automatically re-encode stored passwords using scram-sha-256 to crdb-bcryptServerless/Dedicated/Self-Hosted
server.user_login.min_password_length
integer1the minimum length accepted for passwords set in cleartext via SQL. Note that a value lower than 1 is ignored: passwords cannot be empty in any case. This setting only applies when adding new users or altering an existing user's password; it will not affect existing logins.Serverless/Dedicated/Self-Hosted
server.user_login.password_encryption
enumerationscram-sha-256which hash method to use to encode cleartext passwords passed via ALTER/CREATE USER/ROLE WITH PASSWORD [crdb-bcrypt = 2, scram-sha-256 = 3]Serverless/Dedicated/Self-Hosted
server.user_login.password_hashes.default_cost.crdb_bcrypt
integer10the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method crdb-bcrypt (allowed range: 4-31)Serverless/Dedicated/Self-Hosted
server.user_login.password_hashes.default_cost.scram_sha_256
integer10610the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method scram-sha-256 (allowed range: 4096-240000000000)Serverless/Dedicated/Self-Hosted
server.user_login.rehash_scram_stored_passwords_on_cost_change.enabled
booleantrueif server.user_login.password_hashes.default_cost.scram_sha_256 differs from, the cost in a stored hash, this controls whether to automatically re-encode stored passwords using scram-sha-256 with the new default costServerless/Dedicated/Self-Hosted
server.user_login.timeout
duration10stimeout after which client authentication times out if some system range is unavailable (0 = no timeout)Serverless/Dedicated/Self-Hosted
server.user_login.upgrade_bcrypt_stored_passwords_to_scram.enabled
booleantrueif server.user_login.password_encryption=scram-sha-256, this controls whether to automatically re-encode stored passwords using crdb-bcrypt to scram-sha-256Serverless/Dedicated/Self-Hosted
server.web_session.purge.ttl
duration1h0m0sif nonzero, entries in system.web_sessions older than this duration are periodically purgedServerless/Dedicated/Self-Hosted
server.web_session.timeout
(alias: server.web_session_timeout)
duration168h0m0sthe duration that a newly created web session will be validServerless/Dedicated/Self-Hosted
spanconfig.bounds.enabled
booleantruedictates whether span config bounds are consulted when serving span configs for secondary tenantsDedicated/Self-Hosted
spanconfig.range_coalescing.system.enabled
(alias: spanconfig.storage_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs, for the ranges specific to the system tenantDedicated/Self-Hosted
spanconfig.range_coalescing.application.enabled
(alias: spanconfig.tenant_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs across all secondary tenant keyspacesDedicated/Self-Hosted
sql.auth.change_own_password.enabled
booleanfalsecontrols whether a user is allowed to change their own password, even if they have no other privilegesServerless/Dedicated/Self-Hosted
sql.auth.grant_option_for_owner.enabled
booleantruedetermines whether the GRANT OPTION for privileges is implicitly given to the owner of an objectServerless/Dedicated/Self-Hosted
sql.auth.grant_option_inheritance.enabled
booleantruedetermines whether the GRANT OPTION for privileges is inherited through role membershipServerless/Dedicated/Self-Hosted
sql.auth.public_schema_create_privilege.enabled
booleantruedetermines whether to grant all users the CREATE privileges on the public schema when it is createdServerless/Dedicated/Self-Hosted
sql.auth.skip_underlying_view_privilege_checks.enabled
booleantruedetermines whether to skip privilege checks on tables underlying views. When enabled, users with SELECT privileges on a view can query it regardless of their privileges on the underlying tables, and row-level security policies are evaluated as the invoking user rather than the view owner. This restores pre-v26.2 behavior.Serverless/Dedicated/Self-Hosted
sql.closed_session_cache.capacity
integer1000the maximum number of sessions in the cacheServerless/Dedicated/Self-Hosted
sql.closed_session_cache.time_to_live
integer3600the maximum time to live, in secondsServerless/Dedicated/Self-Hosted
sql.contention.event_store.capacity
byte size64 MiBthe in-memory storage capacity per-node of contention event storeServerless/Dedicated/Self-Hosted
sql.contention.event_store.duration_threshold
duration0sminimum contention duration to cause the contention events to be collected into crdb_internal.transaction_contention_eventsServerless/Dedicated/Self-Hosted
sql.contention.record_serialization_conflicts.enabled
booleantrueenables recording 40001 errors with conflicting txn meta as SERIALIZATION_CONFLICTcontention events into crdb_internal.transaction_contention_eventsServerless/Dedicated/Self-Hosted
sql.contention.txn_id_cache.max_size
byte size64 MiBthe maximum byte size TxnID cache will use (set to 0 to disable)Serverless/Dedicated/Self-Hosted
sql.cross_db_fks.enabled
booleanfalseif true, creating foreign key references across databases is allowedServerless/Dedicated/Self-Hosted
sql.cross_db_sequence_owners.enabled
booleanfalseif true, creating sequences owned by tables from other databases is allowedServerless/Dedicated/Self-Hosted
sql.cross_db_sequence_references.enabled
booleanfalseif true, sequences referenced by tables from other databases are allowedServerless/Dedicated/Self-Hosted
sql.cross_db_views.enabled
booleanfalseif true, creating views that refer to other databases is allowedServerless/Dedicated/Self-Hosted
sql.defaults.cost_scans_with_default_col_size.enabled
booleanfalsesetting to true uses the same size for all columns to compute scan cost
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.datestyle
enumerationiso, mdydefault value for DateStyle session setting [iso, mdy = 0, iso, dmy = 1, iso, ymd = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.default_hash_sharded_index_bucket_count
integer16used as bucket count if bucket count is not specified in hash sharded index definition
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.default_int_size
integer8the size, in bytes, of an INT type
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.disallow_full_table_scans.enabled
booleanfalsesetting to true rejects queries that have planned a full table scan; set large_full_scan_rows > 0 to allow small full table scans estimated to read fewer than large_full_scan_rows
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.distsql
enumerationautodefault distributed SQL execution mode [off = 0, auto = 1, on = 2, always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_alter_column_type.enabled
booleanfalsedefault value for experimental_alter_column_type session setting; enables the use of ALTER COLUMN TYPE for general conversions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_distsql_planning
enumerationoffdefault experimental_distsql_planning mode; enables experimental opt-driven DistSQL planning [off = 0, on = 1]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_enable_unique_without_index_constraints.enabled
booleanfalsedefault value for experimental_enable_unique_without_index_constraints session setting;disables unique without index constraints by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_implicit_column_partitioning.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for the use of implicit column partitioning
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.experimental_temporary_tables.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for use of temporary tables by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.foreign_key_cascades_limit
integer10000default value for foreign_key_cascades_limit session setting; limits the number of cascading operations that run as part of a single query
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.idle_in_session_timeout
duration0sdefault value for the idle_in_session_timeout; default value for the idle_in_session_timeout session setting; controls the duration a session is permitted to idle before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.idle_in_transaction_session_timeout
duration0sdefault value for the idle_in_transaction_session_timeout; controls the duration a session is permitted to idle in a transaction before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.implicit_select_for_update.enabled
booleantruedefault value for enable_implicit_select_for_update session setting; enables FOR UPDATE locking during the row-fetch phase of mutation statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.insert_fast_path.enabled
booleantruedefault value for enable_insert_fast_path session setting; enables a specialized insert path
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.intervalstyle
enumerationpostgresdefault value for IntervalStyle session setting [postgres = 0, iso_8601 = 1, sql_standard = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.large_full_scan_rows
float0default value for large_full_scan_rows session variable which determines the table size at which full scans are considered large and disallowed when disallow_full_table_scans is set to true; set to 0 to reject all full table or full index scans when disallow_full_table_scans is true
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.locality_optimized_partitioned_index_scan.enabled
booleantruedefault value for locality_optimized_partitioned_index_scan session setting; enables searching for rows in the current region before searching remote regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.lock_timeout
duration0sdefault value for the lock_timeout; default value for the lock_timeout session setting; controls the duration a query is permitted to wait while attempting to acquire a lock on a key or while blocking on an existing lock in order to perform a non-locking read on a key; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.on_update_rehome_row.enabled
booleantruedefault value for on_update_rehome_row; enables ON UPDATE rehome_row() expressions to trigger on updates
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.optimizer_use_histograms.enabled
booleantruedefault value for optimizer_use_histograms session setting; enables usage of histograms in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.optimizer_use_multicol_stats.enabled
booleantruedefault value for optimizer_use_multicol_stats session setting; enables usage of multi-column stats in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.override_alter_primary_region_in_super_region.enabled
booleanfalsedefault value for override_alter_primary_region_in_super_region; allows for altering the primary region even if the primary region is a member of a super region
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.override_multi_region_zone_config.enabled
booleanfalsedefault value for override_multi_region_zone_config; allows for overriding the zone configs of a multi-region table or database
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.prefer_lookup_joins_for_fks.enabled
booleanfalsedefault value for prefer_lookup_joins_for_fks session setting; causes foreign key operations to use lookup joins when possible
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.primary_region
stringif not empty, all databases created without a PRIMARY REGION will implicitly have the given PRIMARY REGION
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.reorder_joins_limit
integer8default number of joins to reorder
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.require_explicit_primary_keys.enabled
booleanfalsedefault value for requiring explicit primary keys in CREATE TABLE statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.results_buffer.size
byte size512 KiBdefault size of the buffer that accumulates results for a statement or a batch of statements before they are sent to the client. This can be overridden on an individual connection with the 'results_buffer_size' parameter. Note that auto-retries generally only happen while no results have been delivered to the client, so reducing this size can increase the number of retriable errors a client receives. On the other hand, increasing the buffer size can increase the delay until the client receives the first result row. Updating the setting only affects new connections. Setting to 0 disables any buffering.
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.serial_normalization
enumerationrowiddefault handling of SERIAL in table definitions [rowid = 0, virtual_sequence = 1, sql_sequence = 2, sql_sequence_cached = 3, unordered_rowid = 4, sql_sequence_cached_node = 5]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.statement_timeout
duration0sdefault value for the statement_timeout; default value for the statement_timeout session setting; controls the duration a query is permitted to run before it is canceled; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.stub_catalog_tables.enabled
booleantruedefault value for stub_catalog_tables session setting
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.super_regions.enabled
booleanfalsedefault value for enable_super_regions; allows for the usage of super regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_read_err
integer0the limit for the number of rows read by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_read_log
integer0the threshold for the number of rows read by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_written_err
integer0the limit for the number of rows written by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.transaction_rows_written_log
integer0the threshold for the number of rows written by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.use_declarative_schema_changer
enumerationondefault value for use_declarative_schema_changer session setting;disables new schema changer by default [off = 0, on = 1, unsafe = 2, unsafe_always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.vectorize
enumerationondefault vectorize mode [on = 0, on = 1, on = 2, experimental_always = 3, off = 4]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.defaults.zigzag_join.enabled
booleanfalsedefault value for enable_zigzag_join session setting; disallows use of zig-zag join by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Serverless/Dedicated/Self-Hosted
sql.distsql.temp_storage.workmem
byte size64 MiBmaximum amount of memory in bytes a processor can use before falling back to temp storageServerless/Dedicated/Self-Hosted
sql.guardrails.max_row_size_err
byte size512 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an error is returned; use 0 to disableServerless/Dedicated/Self-Hosted
sql.guardrails.max_row_size_log
byte size64 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an event is logged to SQL_PERF (or SQL_INTERNAL_PERF if the mutating statement was internal); use 0 to disableServerless/Dedicated/Self-Hosted
sql.hash_sharded_range_pre_split.max
integer16max pre-split ranges to have when adding hash sharded index to an existing tableServerless/Dedicated/Self-Hosted
sql.index_recommendation.drop_unused_duration
duration168h0m0sthe index unused duration at which we begin to recommend dropping the indexServerless/Dedicated/Self-Hosted
sql.insights.anomaly_detection.enabled
booleantrueenable per-fingerprint latency recording and anomaly detectionServerless/Dedicated/Self-Hosted
sql.insights.anomaly_detection.latency_threshold
duration50msstatements must surpass this threshold to trigger anomaly detection and identificationServerless/Dedicated/Self-Hosted
sql.insights.anomaly_detection.memory_limit
byte size1.0 MiBthe maximum amount of memory allowed for tracking statement latenciesServerless/Dedicated/Self-Hosted
sql.insights.execution_insights_capacity
integer1000the size of the per-node store of execution insightsServerless/Dedicated/Self-Hosted
sql.insights.high_retry_count.threshold
integer10the number of retries a slow statement must have undergone for its high retry count to be highlighted as a potential problemServerless/Dedicated/Self-Hosted
sql.insights.latency_threshold
duration100msamount of time after which an executing statement is considered slow. Use 0 to disable.Serverless/Dedicated/Self-Hosted
sql.log.redact_names.enabled
booleanfalseif set, schema object identifers are redacted in SQL statements that appear in event logsServerless/Dedicated/Self-Hosted
sql.log.slow_query.experimental_full_table_scans.enabled
booleanfalsewhen set to true, statements that perform a full table/index scan will be logged to the slow query log even if they do not meet the latency threshold. Must have the slow query log enabled for this setting to have any effect.Serverless/Dedicated/Self-Hosted
sql.log.slow_query.internal_queries.enabled
booleanfalsewhen set to true, internal queries which exceed the slow query log threshold are logged to a separate log. Must have the slow query log enabled for this setting to have any effect.Serverless/Dedicated/Self-Hosted
sql.log.slow_query.latency_threshold
duration0swhen set to non-zero, log statements whose service latency exceeds the threshold to a secondary logger on each nodeServerless/Dedicated/Self-Hosted
sql.log.user_audit
stringuser/role-based audit logging configuration. An enterprise license is required for this cluster setting to take effect.Serverless/Dedicated/Self-Hosted
sql.log.user_audit.reduced_config.enabled
booleanfalseenables logic to compute a reduced audit configuration, computing the audit configuration only once at session start instead of at each SQL event. The tradeoff with the increase in performance (~5%), is that changes to the audit configuration (user role memberships/cluster setting) are not reflected within session. Users will need to start a new session to see these changes in their auditing behaviour.Serverless/Dedicated/Self-Hosted
sql.metrics.application_name.enabled
booleanfalsewhen enabled, SQL metrics would export application name as and additional label as part of child metrics. The number of unique label combinations is limited to 5000 by default.Serverless/Dedicated/Self-Hosted
sql.metrics.database_name.enabled
booleanfalsewhen enabled, SQL metrics would export database name as and additional label as part of child metrics. The number of unique label combinations is limited to 5000 by default.Serverless/Dedicated/Self-Hosted
sql.metrics.index_usage_stats.enabled
booleantruecollect per index usage statisticsServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_reported_stmt_fingerprints
integer100000the maximum number of reported statement fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_reported_txn_fingerprints
integer100000the maximum number of reported transaction fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_stmt_fingerprints
integer7500the maximum number of statement fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.max_mem_txn_fingerprints
integer7500the maximum number of transaction fingerprints stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.dump_to_logs.enabled
(alias: sql.metrics.statement_details.dump_to_logs)
booleanfalsedump collected statement statistics to node logs when periodically clearedServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.enabled
booleantruecollect per-statement query statisticsServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.gateway_node.enabled
booleanfalsesave the gateway node for each statement fingerprint. If false, the value will be stored as 0.Serverless/Dedicated/Self-Hosted
sql.metrics.statement_details.index_recommendation_collection.enabled
booleantruegenerate an index recommendation for each fingerprint IDServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.max_mem_reported_idx_recommendations
integer5000the maximum number of reported index recommendation info stored in memoryServerless/Dedicated/Self-Hosted
sql.metrics.statement_details.threshold
duration0sminimum execution time to cause statement statistics to be collected. If configured, no transaction stats are collected.Serverless/Dedicated/Self-Hosted
sql.metrics.transaction_details.enabled
booleantruecollect per-application transaction statisticsServerless/Dedicated/Self-Hosted
sql.multiple_modifications_of_table.enabled
booleanfalseif true, allow statements containing multiple INSERT ON CONFLICT, UPSERT, UPDATE, or DELETE subqueries modifying the same table, at the risk of data corruption if the same row is modified multiple times by a single statement (multiple INSERT subqueries without ON CONFLICT cannot cause corruption and are always allowed)Serverless/Dedicated/Self-Hosted
sql.multiregion.drop_primary_region.enabled
booleantrueallows dropping the PRIMARY REGION of a database if it is the last regionServerless/Dedicated/Self-Hosted
sql.notices.enabled
booleantrueenable notices in the server/client protocol being sentServerless/Dedicated/Self-Hosted
sql.optimizer.uniqueness_checks_for_gen_random_uuid.enabled
booleanfalseif enabled, uniqueness checks may be planned for mutations of UUID columns updated with gen_random_uuid(); otherwise, uniqueness is assumed due to near-zero collision probabilityServerless/Dedicated/Self-Hosted
sql.schema.auto_unlock.enabled
booleantruecontrols whether DDL operations will attempt to automatically unlock and re-lock schema_locked tables. When this setting is false, DDL on schema_locked tables is blocked unless the user manually unlocks the table first. The schema_locked storage parameter improves changefeed performance by locking the table's schema from the perspective of the changefeed.Serverless/Dedicated/Self-Hosted
sql.schema.telemetry.recurrence
string@weeklycron-tab recurrence for SQL schema telemetry jobDedicated/Self-hosted (read-write); Serverless (read-only)
sql.spatial.experimental_box2d_comparison_operators.enabled
booleanfalseenables the use of certain experimental box2d comparison operatorsServerless/Dedicated/Self-Hosted
sql.stats.activity.persisted_rows.max
integer200000maximum number of rows of statement and transaction activity that will be persisted in the system tablesServerless/Dedicated/Self-Hosted
sql.stats.automatic_collection.enabled
booleantrueautomatic statistics collection modeServerless/Dedicated/Self-Hosted
sql.stats.automatic_collection.fraction_stale_rows
float0.2target fraction of stale rows per table that will trigger a statistics refreshServerless/Dedicated/Self-Hosted
sql.stats.automatic_collection.min_stale_rows
integer500target minimum number of stale rows per table that will trigger a statistics refreshServerless/Dedicated/Self-Hosted
sql.stats.automatic_full_collection.enabled
booleantrueautomatic full statistics collection modeServerless/Dedicated/Self-Hosted
sql.stats.automatic_partial_collection.enabled
booleantrueautomatic partial statistics collection modeServerless/Dedicated/Self-Hosted
sql.stats.automatic_partial_collection.fraction_stale_rows
float0.05target fraction of stale rows per table that will trigger a partial statistics refreshServerless/Dedicated/Self-Hosted
sql.stats.automatic_partial_collection.min_stale_rows
integer100target minimum number of stale rows per table that will trigger a partial statistics refreshServerless/Dedicated/Self-Hosted
sql.stats.cleanup.recurrence
string@hourlycron-tab recurrence for SQL Stats cleanup jobServerless/Dedicated/Self-Hosted
sql.stats.detailed_latency_metrics.enabled
booleanfalselabel latency metrics with the statement fingerprint. Workloads with tens of thousands of distinct query fingerprints should leave this setting false. (experimental, affects performance for workloads with high fingerprint cardinality)Serverless/Dedicated/Self-Hosted
sql.stats.error_on_concurrent_create_stats.enabled
booleantrueset to true to error on concurrent CREATE STATISTICS jobs, instead of skipping themServerless/Dedicated/Self-Hosted
sql.stats.flush.enabled
booleantrueif set, SQL execution statistics are periodically flushed to diskServerless/Dedicated/Self-Hosted
sql.stats.flush.interval
duration10m0sthe interval at which SQL execution statistics are flushed to disk, this value must be less than or equal to 1 hourServerless/Dedicated/Self-Hosted
sql.stats.forecasts.enabled
booleantruewhen true, enables generation of statistics forecasts by default for all tablesServerless/Dedicated/Self-Hosted
sql.stats.forecasts.max_decrease
float0.3333333333333333the most a prediction is allowed to decrease, expressed as the minimum ratio of the prediction to the lowest prior observationServerless/Dedicated/Self-Hosted
sql.stats.forecasts.min_goodness_of_fit
float0.95the minimum R² (goodness of fit) measurement required from all predictive models to use a forecastServerless/Dedicated/Self-Hosted
sql.stats.forecasts.min_observations
integer3the mimimum number of observed statistics required to produce a statistics forecastServerless/Dedicated/Self-Hosted
sql.stats.histogram_buckets.count
integer200maximum number of histogram buckets to build during table statistics collectionServerless/Dedicated/Self-Hosted
sql.stats.histogram_buckets.include_most_common_values.enabled
booleantruewhether to include most common values as histogram bucketsServerless/Dedicated/Self-Hosted
sql.stats.histogram_buckets.max_fraction_most_common_values
float0.1maximum fraction of histogram buckets to use for most common valuesServerless/Dedicated/Self-Hosted
sql.stats.histogram_collection.enabled
booleantruehistogram collection modeServerless/Dedicated/Self-Hosted
sql.stats.histogram_samples.count
integer0number of rows sampled for histogram construction during table statistics collection. Not setting this or setting a value of 0 means that a reasonable sample size will be automatically picked based on the table size.Serverless/Dedicated/Self-Hosted
sql.stats.multi_column_collection.enabled
booleantruemulti-column statistics collection modeServerless/Dedicated/Self-Hosted
sql.stats.non_default_columns.min_retention_period
duration24h0m0sminimum retention period for table statistics collected on non-default columnsServerless/Dedicated/Self-Hosted
sql.stats.non_indexed_json_histograms.enabled
booleanfalseset to true to collect table statistics histograms on non-indexed JSON columnsServerless/Dedicated/Self-Hosted
sql.stats.persisted_rows.max
integer1000000maximum number of rows of statement and transaction statistics that will be persisted in the system tables before compaction beginsServerless/Dedicated/Self-Hosted
sql.stats.post_events.enabled
booleanfalseif set, an event is logged for every successful CREATE STATISTICS jobServerless/Dedicated/Self-Hosted
sql.stats.response.max
integer20000the maximum number of statements and transaction stats returned in a CombinedStatements requestServerless/Dedicated/Self-Hosted
sql.stats.response.show_internal.enabled
booleanfalsecontrols if statistics for internal executions should be returned by the CombinedStatements and if internal sessions should be returned by the ListSessions endpoints. These endpoints are used to display statistics on the SQL Activity pagesServerless/Dedicated/Self-Hosted
sql.stats.system_tables.enabled
booleantruewhen true, enables use of statistics on system tables by the query optimizerServerless/Dedicated/Self-Hosted
sql.stats.system_tables_autostats.enabled
booleantruewhen true, enables automatic collection of statistics on system tablesServerless/Dedicated/Self-Hosted
sql.stats.table_statistics_cache.capacity
integer256the maximum number of table statistics entries stored in the LRU cache. Each cache entry corresponds to a single table.Serverless/Dedicated/Self-Hosted
sql.stats.virtual_computed_columns.enabled
booleantrueset to true to collect table statistics on virtual computed columnsServerless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.enabled
booleanfalsewhen set to true, executed queries will emit an event on the telemetry logging channelServerless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.internal.enabled
booleanfalsewhen set to true, internal queries will be sampled in telemetry loggingServerless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample executions for telemetry, note that it is recommended that this value shares a log-line limit of 10 logs per second on the telemetry pipeline with all other telemetry events. If sampling mode is set to 'transaction', this value is ignored.Serverless/Dedicated/Self-Hosted
sql.telemetry.query_sampling.mode
enumerationstatementthe execution level used for telemetry sampling. If set to 'statement', events are sampled at the statement execution level. If set to 'transaction', events are sampled at the transaction execution level, i.e. all statements for a transaction will be logged and are counted together as one sampled event (events are still emitted one per statement). [statement = 0, transaction = 1]Serverless/Dedicated/Self-Hosted
sql.telemetry.transaction_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample transactions for telemetry. If sampling mode is set to 'statement', this setting is ignored. In practice, this means that we only sample a transaction if 1/max_event_frequency seconds have elapsed since the last transaction was sampled.Serverless/Dedicated/Self-Hosted
sql.telemetry.transaction_sampling.statement_events_per_transaction.max
integer50the maximum number of statement events to log for every sampled transaction. Note that statements that are logged by force do not adhere to this limit.Serverless/Dedicated/Self-Hosted
sql.temp_object_cleaner.cleanup_interval
duration30m0show often to clean up orphaned temporary objectsServerless/Dedicated/Self-Hosted
sql.temp_object_cleaner.wait_interval
duration30m0show long after creation a temporary object will be cleaned upServerless/Dedicated/Self-Hosted
sql.log.all_statements.enabled
(alias: sql.trace.log_statement_execute)
booleanfalseset to true to enable logging of all executed statementsServerless/Dedicated/Self-Hosted
sql.trace.stmt.enable_threshold
duration0senables tracing on all statements; statements executing for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting applies to individual statements within a transaction and is therefore finer-grained than sql.trace.txn.enable_thresholdServerless/Dedicated/Self-Hosted
sql.trace.txn.enable_threshold
duration0senables transaction traces for transactions exceeding this duration, used with `sql.trace.txn.sample_rate`Serverless/Dedicated/Self-Hosted
sql.trace.txn.sample_rate
float1enables probabilistic transaction tracing. It should be used in conjunction with `sql.trace.txn.enable_threshold`. A percentage of transactions between 0 and 1.0 will have tracing enabled, and only those which exceed the configured threshold will be logged.Serverless/Dedicated/Self-Hosted
sql.ttl.changefeed_replication.disabled
booleanfalseif true, deletes issued by TTL will not be replicated via changefeeds (this setting will be ignored by changefeeds that have the ignore_disable_changefeed_replication option set; such changefeeds will continue to replicate all TTL deletes)Serverless/Dedicated/Self-Hosted
sql.ttl.default_delete_batch_size
integer100default amount of rows to delete in a single query during a TTL jobServerless/Dedicated/Self-Hosted
sql.ttl.default_delete_rate_limit
integer100default delete rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Serverless/Dedicated/Self-Hosted
sql.ttl.default_select_batch_size
integer500default amount of rows to select in a single query during a TTL jobServerless/Dedicated/Self-Hosted
sql.ttl.default_select_rate_limit
integer0default select rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Serverless/Dedicated/Self-Hosted
sql.ttl.job.enabled
booleantruewhether the TTL job is enabledServerless/Dedicated/Self-Hosted
sql.txn.read_committed_isolation.enabled
booleantrueset to true to allow transactions to use the READ COMMITTED isolation level if specified by BEGIN/SET commandsServerless/Dedicated/Self-Hosted
sql.txn.repeatable_read_isolation.enabled
(alias: sql.txn.snapshot_isolation.enabled)
booleanfalseset to true to allow transactions to use the REPEATABLE READ isolation level if specified by BEGIN/SET commandsServerless/Dedicated/Self-Hosted
sql.txn_fingerprint_id_cache.capacity
integer100the maximum number of txn fingerprint IDs storedServerless/Dedicated/Self-Hosted
sql.vecindex.stalled_op.timeout
duration100msamount of time before other vector index workers will assist with a stalled background fixupServerless/Dedicated/Self-Hosted
storage.columnar_blocks.enabled
booleantrueset to true to enable columnar-blocks to store KVs in a columnar formatDedicated/Self-hosted (read-write); Serverless (read-only)
storage.delete_compaction_excise.enabled
booleantrueset to false to direct Pebble to not partially excise sstables in delete-only compactionsDedicated/Self-hosted (read-write); Serverless (read-only)
storage.ingest_split.enabled
booleantrueset to false to disable ingest-time splitting that lowers write-amplificationDedicated/Self-Hosted
storage.ingestion.value_blocks.enabled
booleantrueset to true to enable writing of value blocks in ingestion sstablesServerless/Dedicated/Self-Hosted
storage.max_sync_duration
duration20smaximum duration for disk operations; any operations that take longer than this setting trigger a warning log entry or process crashDedicated/Self-hosted (read-write); Serverless (read-only)
storage.max_sync_duration.fatal.enabled
booleantrueif true, fatal the process when a disk operation exceeds storage.max_sync_durationServerless/Dedicated/Self-Hosted
storage.sstable.compression_algorithm
enumerationsnappydetermines the compression algorithm to use when compressing sstable data blocks for use in a Pebble store; [snappy = 1, zstd = 2, none = 3]Dedicated/Self-hosted (read-write); Serverless (read-only)
storage.sstable.compression_algorithm_backup_storage
enumerationsnappydetermines the compression algorithm to use when compressing sstable data blocks for backup row data storage; [snappy = 1, zstd = 2, none = 3]Dedicated/Self-hosted (read-write); Serverless (read-only)
storage.sstable.compression_algorithm_backup_transport
enumerationsnappydetermines the compression algorithm to use when compressing sstable data blocks for backup transport; [snappy = 1, zstd = 2, none = 3]Dedicated/Self-hosted (read-write); Serverless (read-only)
storage.wal_failover.unhealthy_op_threshold
duration100msthe latency of a WAL write considered unhealthy and triggers a failover to a secondary WAL locationDedicated/Self-Hosted
timeseries.storage.enabled
booleantrueif set, periodic timeseries data is stored within the cluster; disabling is not recommended unless you are storing the data elsewhereDedicated/Self-Hosted
timeseries.storage.resolution_10s.ttl
duration240h0m0sthe maximum age of time series data stored at the 10 second resolution. Data older than this is subject to rollup and deletion.Dedicated/Self-hosted (read-write); Serverless (read-only)
timeseries.storage.resolution_30m.ttl
duration2160h0m0sthe maximum age of time series data stored at the 30 minute resolution. Data older than this is subject to deletion.Dedicated/Self-hosted (read-write); Serverless (read-only)
trace.debug_http_endpoint.enabled
(alias: trace.debug.enable)
booleanfalseif set, traces for recent requests can be seen at https://<ui>/debug/requestsServerless/Dedicated/Self-Hosted
trace.opentelemetry.collector
stringaddress of an OpenTelemetry trace collector to receive traces using the otel gRPC protocol, as <host>:<port>. If no port is specified, 4317 will be used.Serverless/Dedicated/Self-Hosted
trace.snapshot.rate
duration0sif non-zero, interval at which background trace snapshots are capturedServerless/Dedicated/Self-Hosted
trace.span_registry.enabled
booleanfalseif set, ongoing traces can be seen at https://<ui>/#/debug/tracezServerless/Dedicated/Self-Hosted
trace.zipkin.collector
stringthe address of a Zipkin instance to receive traces, as <host>:<port>. If no port is specified, 9411 will be used.Serverless/Dedicated/Self-Hosted
ui.database_locality_metadata.enabled
booleantrueif enabled shows extended locality data about databases and tables in DB Console which can be expensive to computeServerless/Dedicated/Self-Hosted
ui.default_timezone
stringthe default timezone used to format timestamps in the uiServerless/Dedicated/Self-Hosted
ui.display_timezone
enumerationetc/utcthe timezone used to format timestamps in the ui. This setting is deprecatedand will be removed in a future version. Use the 'ui.default_timezone' setting instead. 'ui.default_timezone' takes precedence over this setting. [etc/utc = 0, america/new_york = 1]Serverless/Dedicated/Self-Hosted
version
version25.2set the active cluster version in the format '<major>.<minor>'Serverless/Dedicated/Self-Hosted
diff --git a/src/current/_includes/cockroach-generated/release-25.2/sql/aggregates.md b/src/current/_includes/cockroach-generated/release-25.2/sql/aggregates.md new file mode 100644 index 00000000000..3213f0f02a8 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.2/sql/aggregates.md @@ -0,0 +1,579 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_agg(arg1: bool) → bool[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bool[]) → bool[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes) → bytes[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes[]) → bytes[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date) → date[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date[]) → date[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal) → decimal[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal[]) → decimal[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float) → float[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float[]) → float[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet) → inet[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet[]) → inet[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int) → int[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int[]) → int[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval) → interval[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval[]) → interval[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string) → string[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string[]) → string[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time) → time[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time[]) → time[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp) → timestamp[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp[]) → timestamp[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz) → timestamptz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz[]) → timestamptz[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid) → uuid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid[]) → uuid[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum) → anyenum[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum[]) → anyenum[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d) → box2d[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d[]) → box2d[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography) → geography[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography[]) → geography[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry) → geometry[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry[]) → geometry[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb) → jsonb[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb[]) → jsonb[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid) → oid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid[]) → oid[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn) → pg_lsn[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn[]) → pg_lsn[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor) → refcursor[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor[]) → refcursor[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz) → timetz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz[]) → timetz[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple) → tuple[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple[]) → tuple[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit) → varbit[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit[]) → varbit[][]

Aggregates the selected values into an array.

+		Immutable
array_cat_agg(arg1: bool[]) → bool[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: bytes[]) → bytes[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: date[]) → date[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: decimal[]) → decimal[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: float[]) → float[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: inet[]) → inet[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: int[]) → int[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: interval[]) → interval[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: string[]) → string[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: time[]) → time[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamp[]) → timestamp[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamptz[]) → timestamptz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: uuid[]) → uuid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: anyenum[]) → anyenum[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: box2d[]) → box2d[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geography[]) → geography[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geometry[]) → geometry[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: jsonb[]) → jsonb[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: oid[]) → oid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: pg_lsn[]) → pg_lsn[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: refcursor[]) → refcursor[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timetz[]) → timetz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: tuple[]) → tuple[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: varbit[]) → varbit[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
avg(arg1: decimal) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: float) → float

Calculates the average of the selected values.

+		Immutable
avg(arg1: int) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: interval) → interval

Calculates the average of the selected values.

+		Immutable
bit_and(arg1: int) → int

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_and(arg1: varbit) → varbit

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: int) → int

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: varbit) → varbit

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bool_and(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
bool_or(arg1: bool) → bool

Calculates the boolean value of ORing all selected values.

+		Immutable
concat_agg(arg1: bytes) → bytes

Concatenates all selected values.

+		Immutable
concat_agg(arg1: string) → string

Concatenates all selected values.

+		Immutable
corr(arg1: decimal, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
count(arg1: anyelement) → int

Calculates the number of selected elements.

+		Immutable
count_rows() → int

Calculates the number of rows.

+		Immutable
covar_pop(arg1: decimal, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
every(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
json_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
json_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
jsonb_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
jsonb_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
max(arg1: bool) → bool

Identifies the maximum selected value.

+		Immutable
max(arg1: bytes) → bytes

Identifies the maximum selected value.

+		Immutable
max(arg1: date) → date

Identifies the maximum selected value.

+		Immutable
max(arg1: decimal) → decimal

Identifies the maximum selected value.

+		Immutable
max(arg1: float) → float

Identifies the maximum selected value.

+		Immutable
max(arg1: inet) → inet

Identifies the maximum selected value.

+		Immutable
max(arg1: int) → int

Identifies the maximum selected value.

+		Immutable
max(arg1: interval) → interval

Identifies the maximum selected value.

+		Immutable
max(arg1: string) → string

Identifies the maximum selected value.

+		Immutable
max(arg1: time) → time

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamp) → timestamp

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamptz) → timestamptz

Identifies the maximum selected value.

+		Immutable
max(arg1: uuid) → uuid

Identifies the maximum selected value.

+		Immutable
max(arg1: anyenum) → anyenum

Identifies the maximum selected value.

+		Immutable
max(arg1: box2d) → box2d

Identifies the maximum selected value.

+		Immutable
max(arg1: collatedstring{*}) → collatedstring{*}

Identifies the maximum selected value.

+		Immutable
max(arg1: geography) → geography

Identifies the maximum selected value.

+		Immutable
max(arg1: geometry) → geometry

Identifies the maximum selected value.

+		Immutable
max(arg1: jsonb) → jsonb

Identifies the maximum selected value.

+		Immutable
max(arg1: oid) → oid

Identifies the maximum selected value.

+		Immutable
max(arg1: pg_lsn) → pg_lsn

Identifies the maximum selected value.

+		Immutable
max(arg1: timetz) → timetz

Identifies the maximum selected value.

+		Immutable
max(arg1: varbit) → varbit

Identifies the maximum selected value.

+		Immutable
min(arg1: bool) → bool

Identifies the minimum selected value.

+		Immutable
min(arg1: bytes) → bytes

Identifies the minimum selected value.

+		Immutable
min(arg1: date) → date

Identifies the minimum selected value.

+		Immutable
min(arg1: decimal) → decimal

Identifies the minimum selected value.

+		Immutable
min(arg1: float) → float

Identifies the minimum selected value.

+		Immutable
min(arg1: inet) → inet

Identifies the minimum selected value.

+		Immutable
min(arg1: int) → int

Identifies the minimum selected value.

+		Immutable
min(arg1: interval) → interval

Identifies the minimum selected value.

+		Immutable
min(arg1: string) → string

Identifies the minimum selected value.

+		Immutable
min(arg1: time) → time

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamp) → timestamp

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamptz) → timestamptz

Identifies the minimum selected value.

+		Immutable
min(arg1: uuid) → uuid

Identifies the minimum selected value.

+		Immutable
min(arg1: anyenum) → anyenum

Identifies the minimum selected value.

+		Immutable
min(arg1: box2d) → box2d

Identifies the minimum selected value.

+		Immutable
min(arg1: collatedstring{*}) → collatedstring{*}

Identifies the minimum selected value.

+		Immutable
min(arg1: geography) → geography

Identifies the minimum selected value.

+		Immutable
min(arg1: geometry) → geometry

Identifies the minimum selected value.

+		Immutable
min(arg1: jsonb) → jsonb

Identifies the minimum selected value.

+		Immutable
min(arg1: oid) → oid

Identifies the minimum selected value.

+		Immutable
min(arg1: pg_lsn) → pg_lsn

Identifies the minimum selected value.

+		Immutable
min(arg1: timetz) → timetz

Identifies the minimum selected value.

+		Immutable
min(arg1: varbit) → varbit

Identifies the minimum selected value.

+		Immutable
percentile_cont(arg1: float) → float

Continuous percentile: returns a float corresponding to the specified fraction in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float) → interval

Continuous percentile: returns an interval corresponding to the specified fraction in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_cont(arg1: float[]) → float[]

Continuous percentile: returns floats corresponding to the specified fractions in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float[]) → interval[]

Continuous percentile: returns intervals corresponding to the specified fractions in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_disc(arg1: float) → anyelement

Discrete percentile: returns the first input value whose position in the ordering equals or exceeds the specified fraction.

+		Immutable
percentile_disc(arg1: float[]) → anyelement

Discrete percentile: returns input values whose position in the ordering equals or exceeds the specified fractions.

+		Immutable
regr_avgx(arg1: decimal, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_count(arg1: decimal, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_intercept(arg1: decimal, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_r2(arg1: decimal, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_slope(arg1: decimal, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_sxx(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
sqrdiff(arg1: decimal) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: float) → float

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: int) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
st_collect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_extent(arg1: geometry) → box2d

Forms a Box2D that encapsulates all provided geometries.

+		Immutable
st_makeline(arg1: geometry) → geometry

Forms a LineString from Point, MultiPoint or LineStrings. Other shapes will be ignored.

+		Immutable
st_memcollect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_memunion(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
st_union(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
stddev(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: decimal) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: float) → float

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: int) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
string_agg(arg1: bytes, arg2: bytes) → bytes

Concatenates all selected values using the provided delimiter.

+		Immutable
string_agg(arg1: string, arg2: string) → string

Concatenates all selected values using the provided delimiter.

+		Immutable
sum(arg1: decimal) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: float) → float

Calculates the sum of the selected values.

+		Immutable
sum(arg1: int) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: interval) → interval

Calculates the sum of the selected values.

+		Immutable
sum_int(arg1: int) → int

Calculates the sum of the selected values.

+		Immutable
var_pop(arg1: decimal) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: float) → float

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: int) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_samp(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
variance(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
xor_agg(arg1: bytes) → bytes

Calculates the bitwise XOR of the selected values.

+		Immutable
xor_agg(arg1: int) → int

Calculates the bitwise XOR of the selected values.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-25.2/sql/functions.md b/src/current/_includes/cockroach-generated/release-25.2/sql/functions.md new file mode 100644 index 00000000000..7c695326553 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.2/sql/functions.md @@ -0,0 +1,3611 @@ +### Array functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_append(array: bool[], elem: bool) → bool[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: bytes[], elem: bytes) → bytes[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: date[], elem: date) → date[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: decimal[], elem: decimal) → decimal[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: float[], elem: float) → float[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: inet[], elem: inet) → inet[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: int[], elem: int) → int[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: interval[], elem: interval) → interval[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: string[], elem: string) → string[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: time[], elem: time) → time[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamp[], elem: timestamp) → timestamp[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamptz[], elem: timestamptz) → timestamptz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: uuid[], elem: uuid) → uuid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: anyenum[], elem: anyenum) → anyenum[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: box2d[], elem: box2d) → box2d[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geography[], elem: geography) → geography[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geometry[], elem: geometry) → geometry[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: jsonb[], elem: jsonb) → jsonb[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: oid[], elem: oid) → oid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: refcursor[], elem: refcursor) → refcursor[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timetz[], elem: timetz) → timetz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: tuple[], elem: tuple) → tuple[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: varbit[], elem: varbit) → varbit[]

Appends elem to array, returning the result.

+		Immutable
array_cat(left: bool[], right: bool[]) → bool[]

Appends two arrays.

+		Immutable
array_cat(left: bytes[], right: bytes[]) → bytes[]

Appends two arrays.

+		Immutable
array_cat(left: date[], right: date[]) → date[]

Appends two arrays.

+		Immutable
array_cat(left: decimal[], right: decimal[]) → decimal[]

Appends two arrays.

+		Immutable
array_cat(left: float[], right: float[]) → float[]

Appends two arrays.

+		Immutable
array_cat(left: inet[], right: inet[]) → inet[]

Appends two arrays.

+		Immutable
array_cat(left: int[], right: int[]) → int[]

Appends two arrays.

+		Immutable
array_cat(left: interval[], right: interval[]) → interval[]

Appends two arrays.

+		Immutable
array_cat(left: string[], right: string[]) → string[]

Appends two arrays.

+		Immutable
array_cat(left: time[], right: time[]) → time[]

Appends two arrays.

+		Immutable
array_cat(left: timestamp[], right: timestamp[]) → timestamp[]

Appends two arrays.

+		Immutable
array_cat(left: timestamptz[], right: timestamptz[]) → timestamptz[]

Appends two arrays.

+		Immutable
array_cat(left: uuid[], right: uuid[]) → uuid[]

Appends two arrays.

+		Immutable
array_cat(left: anyenum[], right: anyenum[]) → anyenum[]

Appends two arrays.

+		Immutable
array_cat(left: box2d[], right: box2d[]) → box2d[]

Appends two arrays.

+		Immutable
array_cat(left: geography[], right: geography[]) → geography[]

Appends two arrays.

+		Immutable
array_cat(left: geometry[], right: geometry[]) → geometry[]

Appends two arrays.

+		Immutable
array_cat(left: jsonb[], right: jsonb[]) → jsonb[]

Appends two arrays.

+		Immutable
array_cat(left: oid[], right: oid[]) → oid[]

Appends two arrays.

+		Immutable
array_cat(left: pg_lsn[], right: pg_lsn[]) → pg_lsn[]

Appends two arrays.

+		Immutable
array_cat(left: refcursor[], right: refcursor[]) → refcursor[]

Appends two arrays.

+		Immutable
array_cat(left: timetz[], right: timetz[]) → timetz[]

Appends two arrays.

+		Immutable
array_cat(left: tuple[], right: tuple[]) → tuple[]

Appends two arrays.

+		Immutable
array_cat(left: varbit[], right: varbit[]) → varbit[]

Appends two arrays.

+		Immutable
array_length(input: anyelement[], array_dimension: int) → int

Calculates the length of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_lower(input: anyelement[], array_dimension: int) → int

Calculates the minimum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_position(array: bool[], elem: bool) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bool[], elem: bool, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: bytes[], elem: bytes) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bytes[], elem: bytes, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: date[], elem: date) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: date[], elem: date, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: decimal[], elem: decimal) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: decimal[], elem: decimal, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: float[], elem: float) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: float[], elem: float, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: inet[], elem: inet) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: inet[], elem: inet, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: int[], elem: int) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: int[], elem: int, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: interval[], elem: interval) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: interval[], elem: interval, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: string[], elem: string) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: string[], elem: string, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: time[], elem: time) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: time[], elem: time, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timestamp[], elem: timestamp) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamp[], elem: timestamp, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: uuid[], elem: uuid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: uuid[], elem: uuid, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: anyenum[], elem: anyenum) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: anyenum[], elem: anyenum, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: box2d[], elem: box2d) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: box2d[], elem: box2d, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: geography[], elem: geography) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geography[], elem: geography, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: geometry[], elem: geometry) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geometry[], elem: geometry, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: jsonb[], elem: jsonb) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: jsonb[], elem: jsonb, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: oid[], elem: oid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: oid[], elem: oid, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: refcursor[], elem: refcursor) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: refcursor[], elem: refcursor, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timetz[], elem: timetz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timetz[], elem: timetz, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: tuple[], elem: tuple) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: tuple[], elem: tuple, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: varbit[], elem: varbit) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: varbit[], elem: varbit, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_positions(array: bool[], elem: bool) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: bytes[], elem: bytes) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: date[], elem: date) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: decimal[], elem: decimal) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: float[], elem: float) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: inet[], elem: inet) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: int[], elem: int) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: interval[], elem: interval) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: string[], elem: string) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: time[], elem: time) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamp[], elem: timestamp) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamptz[], elem: timestamptz) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: uuid[], elem: uuid) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: anyenum[], elem: anyenum) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: box2d[], elem: box2d) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geography[], elem: geography) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geometry[], elem: geometry) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: jsonb[], elem: jsonb) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: oid[], elem: oid) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: pg_lsn[], elem: pg_lsn) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: refcursor[], elem: refcursor) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timetz[], elem: timetz) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: tuple[], elem: tuple) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: varbit[], elem: varbit) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_prepend(elem: bool, array: bool[]) → bool[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: bytes, array: bytes[]) → bytes[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: date, array: date[]) → date[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: decimal, array: decimal[]) → decimal[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: float, array: float[]) → float[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: inet, array: inet[]) → inet[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: int, array: int[]) → int[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: interval, array: interval[]) → interval[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: string, array: string[]) → string[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: time, array: time[]) → time[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamp, array: timestamp[]) → timestamp[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamptz, array: timestamptz[]) → timestamptz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: uuid, array: uuid[]) → uuid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: anyenum, array: anyenum[]) → anyenum[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: box2d, array: box2d[]) → box2d[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geography, array: geography[]) → geography[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geometry, array: geometry[]) → geometry[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: jsonb, array: jsonb[]) → jsonb[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: oid, array: oid[]) → oid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: pg_lsn, array: pg_lsn[]) → pg_lsn[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: refcursor, array: refcursor[]) → refcursor[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timetz, array: timetz[]) → timetz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: tuple, array: tuple[]) → tuple[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: varbit, array: varbit[]) → varbit[]

Prepends elem to array, returning the result.

+		Immutable
array_remove(array: bool[], elem: bool) → bool[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: bytes[], elem: bytes) → bytes[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: date[], elem: date) → date[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: decimal[], elem: decimal) → decimal[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: float[], elem: float) → float[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: inet[], elem: inet) → inet[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: int[], elem: int) → int[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: interval[], elem: interval) → interval[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: string[], elem: string) → string[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: time[], elem: time) → time[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamp[], elem: timestamp) → timestamp[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamptz[], elem: timestamptz) → timestamptz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: uuid[], elem: uuid) → uuid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: anyenum[], elem: anyenum) → anyenum[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: box2d[], elem: box2d) → box2d[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geography[], elem: geography) → geography[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geometry[], elem: geometry) → geometry[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: jsonb[], elem: jsonb) → jsonb[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: oid[], elem: oid) → oid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: refcursor[], elem: refcursor) → refcursor[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timetz[], elem: timetz) → timetz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: tuple[], elem: tuple) → tuple[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: varbit[], elem: varbit) → varbit[]

Remove from array all elements equal to elem.

+		Immutable
array_replace(array: bool[], toreplace: bool, replacewith: bool) → bool[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: bytes[], toreplace: bytes, replacewith: bytes) → bytes[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: date[], toreplace: date, replacewith: date) → date[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: decimal[], toreplace: decimal, replacewith: decimal) → decimal[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: float[], toreplace: float, replacewith: float) → float[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: inet[], toreplace: inet, replacewith: inet) → inet[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: int[], toreplace: int, replacewith: int) → int[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: interval[], toreplace: interval, replacewith: interval) → interval[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: string[], toreplace: string, replacewith: string) → string[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: time[], toreplace: time, replacewith: time) → time[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamp[], toreplace: timestamp, replacewith: timestamp) → timestamp[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamptz[], toreplace: timestamptz, replacewith: timestamptz) → timestamptz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: uuid[], toreplace: uuid, replacewith: uuid) → uuid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: anyenum[], toreplace: anyenum, replacewith: anyenum) → anyenum[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: box2d[], toreplace: box2d, replacewith: box2d) → box2d[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geography[], toreplace: geography, replacewith: geography) → geography[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geometry[], toreplace: geometry, replacewith: geometry) → geometry[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: jsonb[], toreplace: jsonb, replacewith: jsonb) → jsonb[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: oid[], toreplace: oid, replacewith: oid) → oid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: pg_lsn[], toreplace: pg_lsn, replacewith: pg_lsn) → pg_lsn[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: refcursor[], toreplace: refcursor, replacewith: refcursor) → refcursor[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timetz[], toreplace: timetz, replacewith: timetz) → timetz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: tuple[], toreplace: tuple, replacewith: tuple) → tuple[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: varbit[], toreplace: varbit, replacewith: varbit) → varbit[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_to_string(input: anyelement[], delim: string) → string

Join an array into a string with a delimiter.

+		Stable
array_to_string(input: anyelement[], delimiter: string, null: string) → string

Join an array into a string with a delimiter, replacing NULLs with a null string.

+		Stable
array_upper(input: anyelement[], array_dimension: int) → int

Calculates the maximum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
cardinality(input: anyelement[]) → int

Calculates the number of elements contained in input

+		Immutable
jsonb_array_to_string_array(input: jsonb) → string[]

Convert a JSONB array into a string array.

+		Immutable
string_to_array(str: string, delimiter: string) → string[]

Split a string into components on a delimiter.

+		Immutable
string_to_array(str: string, delimiter: string, null: string) → string[]

Split a string into components on a delimiter with a specified string to consider NULL.

+		Immutable
+ +### BOOL functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Matches case insensetively unescaped with pattern using escape as an escape token.

+		Immutable
inet_contained_by_or_equals(val: inet, container: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_contains_or_equals(container: inet, val: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_same_family(val: inet, val: inet) → bool

Checks if two IP addresses are of the same IP family.

+		Immutable
like_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
not_ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches case insensetively with pattern using escape as an escape token.

+		Immutable
not_like_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
not_similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
+ +### Comparison functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
greatest(anyelement...) → anyelement

Returns the element with the greatest value.

+		Immutable
least(anyelement...) → anyelement

Returns the element with the lowest value.

+		Immutable
num_nonnulls(any...) → int

Returns the number of nonnull arguments.

+		Immutable
num_nulls(any...) → int

Returns the number of null arguments.

+		Immutable
+ +### Cryptographic functions + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crypt(password: string, salt: string) → string

Generates a hash based on a password and salt. The hash algorithm and number of rounds if applicable are encoded in the salt.

+		Immutable
decrypt(data: bytes, key: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
decrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
digest(data: bytes, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
digest(data: string, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
encrypt(data: bytes, key: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
encrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
gen_random_bytes(count: int) → bytes

Returns count cryptographically strong random bytes. At most 1024 bytes can be extracted at a time.

+		Volatile
gen_salt(type: string) → string

Generates a salt for input into the crypt function using the default number of rounds.

+		Volatile
gen_salt(type: string, iter_count: int) → string

Generates a salt for input into the crypt function using iter_count number of rounds.

+		Volatile
hmac(data: bytes, key: bytes, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
hmac(data: string, key: string, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
+ +### DECIMAL functions + + + + + +
Function → ReturnsDescriptionVolatility
hlc_to_timestamp(hlc: decimal) → timestamptz

Returns a TimestampTZ representation of a CockroachDB HLC in decimal form.

+

Note that a TimestampTZ has less precision than a CockroachDB HLC. It is intended as +a convenience function to display HLCs in a print-friendly form. Use the decimal +value if you rely on the HLC for accuracy.

+		Immutable
+ +### Date and time functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
age(end: timestamptz, begin: timestamptz) → interval

Calculates the interval between begin and end, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use the timestamptz subtraction operator.

+		Immutable
age(val: timestamptz) → interval

Calculates the interval between val and the current time, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use now() - timestamptz.

+		Stable
clock_timestamp() → timestamp

Returns the current system time on one of the cluster nodes.

+		Volatile
clock_timestamp() → timestamptz

Returns the current system time on one of the cluster nodes.

+		Volatile
current_date() → date

Returns the date of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_timestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
date_part(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
date_part(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
date_trunc(element: string, input: date) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: interval) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: time) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero.

+

Compatible elements: hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamp) → timestamp

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamptz) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: timestamptz, timezone: string) → timestamptz

Truncates input to precision element in the specified timezone. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
experimental_follower_read_timestamp() → timestamptz

Same as follower_read_timestamp. This name is deprecated.

+		Volatile
experimental_strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
extract(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
extract(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
extract_duration(element: string, input: interval) → int

Extracts element from input. +Compatible elements: hour, minute, second, millisecond, microsecond. +This is deprecated in favor of extract which supports duration.

+		Immutable
follower_read_timestamp() → timestamptz

Returns a timestamp which is very likely to be safe to perform +against a follower replica.

+

This function is intended to be used with an AS OF SYSTEM TIME clause to perform +historical reads against a time which is recent but sufficiently old for reads +to be performed against the closest replica as opposed to the currently +leaseholder for a given range.

+

Note that this function requires an enterprise license on a CCL distribution to +return a result that is less likely the closest replica. It is otherwise +hardcoded as -4.8s from the statement time, which may not result in reading from the +nearest replica.

+		Volatile
localtimestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
make_date(year: int, month: int, day: int) → date

Create date (formatted according to ISO 8601) from year, month, and day fields (negative years signify BC).

+		Immutable
make_timestamp(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamp

Create timestamp (formatted according to ISO 8601) from year, month, day, hour, minute, and seconds fields (negative years signify BC).

+		Immutable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float, timezone: string) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
now() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
overlaps(s1: date, e1: date, s1: date, e2: date) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: date, e1: interval, s1: date, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: interval, s1: time, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: time, s1: time, e2: time) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: interval, s1: timestamp, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: timestamp, s1: timestamp, e2: timestamp) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamptz, e1: interval, s1: timestamptz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Stable
overlaps(s1: timestamptz, e1: timestamptz, s1: timestamptz, e2: timestamptz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: interval, s1: timetz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: timetz, s1: timetz, e2: timetz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
statement_timestamp() → timestamp

Returns the start time of the current statement.

+		Stable
statement_timestamp() → timestamptz

Returns the start time of the current statement.

+		Stable
strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
timeofday() → string

Returns the current system time on one of the cluster nodes as a string.

+		Stable
timezone(timezone: string, time: time) → timetz

Treat given time without time zone as located in the specified time zone.

+		Stable
timezone(timezone: string, timestamp: timestamp) → timestamptz

Treat given time stamp without time zone as located in the specified time zone.

+		Immutable
timezone(timezone: string, timestamptz: timestamptz) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Immutable
timezone(timezone: string, timestamptz_string: string) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Stable
timezone(timezone: string, timetz: timetz) → timetz

Convert given time with time zone to the new time zone.

+		Stable
to_char(date: date) → string

Convert an date to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(date: date, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_char(interval: interval) → string

Convert an interval to a string assuming the Postgres IntervalStyle.

+		Immutable
to_char(interval: interval, format: string) → string

Convert an interval to a string using the given format.

+		Stable
to_char(timestamp: timestamp) → string

Convert an timestamp to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(timestamp: timestamp, format: string) → string

Convert an timestamp to a string using the given format.

+		Stable
to_char(timestamptz: timestamptz, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_timestamp(timestamp: float) → timestamptz

Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to timestamp with time zone.

+		Immutable
transaction_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
with_max_staleness(max_staleness: interval) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_max_staleness(max_staleness: interval, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
+ +### Enum functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
enum_first(val: anyenum) → anyenum

Returns the first value of the input enum type.

+		Stable
enum_last(val: anyenum) → anyenum

Returns the last value of the input enum type.

+		Stable
enum_range(lower: anyenum, upper: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array between the two arguments (inclusive).

+		Stable
enum_range(val: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array.

+		Stable
+ +### FLOAT functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abs(val: decimal) → decimal

Calculates the absolute value of val.

+		Immutable
abs(val: float) → float

Calculates the absolute value of val.

+		Immutable
abs(val: int) → int

Calculates the absolute value of val.

+		Immutable
acos(val: float) → float

Calculates the inverse cosine of val.

+		Immutable
acosd(val: float) → float

Calculates the inverse cosine of val with the result in degrees

+		Immutable
acosh(val: float) → float

Calculates the inverse hyperbolic cosine of val.

+		Immutable
asin(val: float) → float

Calculates the inverse sine of val.

+		Immutable
asind(val: float) → float

Calculates the inverse sine of val with the result in degrees.

+		Immutable
asinh(val: float) → float

Calculates the inverse hyperbolic sine of val.

+		Immutable
atan(val: float) → float

Calculates the inverse tangent of val.

+		Immutable
atan2(x: float, y: float) → float

Calculates the inverse tangent of x/y.

+		Immutable
atan2d(x: float, y: float) → float

Calculates the inverse tangent of x/y with the result in degrees

+		Immutable
atand(val: float) → float

Calculates the inverse tangent of val with the result in degrees.

+		Immutable
atanh(val: float) → float

Calculates the inverse hyperbolic tangent of val.

+		Immutable
cbrt(val: decimal) → decimal

Calculates the cube root (∛) of val.

+		Immutable
cbrt(val: float) → float

Calculates the cube root (∛) of val.

+		Immutable
ceil(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
cos(val: float) → float

Calculates the cosine of val.

+		Immutable
cosd(val: float) → float

Calculates the cosine of val where val is in degrees.

+		Immutable
cosh(val: float) → float

Calculates the hyperbolic cosine of val.

+		Immutable
cot(val: float) → float

Calculates the cotangent of val.

+		Immutable
cotd(val: float) → float

Calculates the cotangent of val where val is in degrees.

+		Immutable
degrees(val: float) → float

Converts val as a radian value to a degree value.

+		Immutable
div(x: decimal, y: decimal) → decimal

Calculates the integer quotient of x/y.

+		Immutable
div(x: float, y: float) → float

Calculates the integer quotient of x/y.

+		Immutable
div(x: int, y: int) → int

Calculates the integer quotient of x/y.

+		Immutable
exp(val: decimal) → decimal

Calculates e ^ val.

+		Immutable
exp(val: float) → float

Calculates e ^ val.

+		Immutable
floor(val: decimal) → decimal

Calculates the largest integer not greater than val.

+		Immutable
floor(val: float) → float

Calculates the largest integer not greater than val.

+		Immutable
floor(val: int) → float

Calculates the largest integer not greater than val.

+		Immutable
isnan(val: decimal) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
isnan(val: float) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
ln(val: decimal) → decimal

Calculates the natural log of val.

+		Immutable
ln(val: float) → float

Calculates the natural log of val.

+		Immutable
log(b: decimal, x: decimal) → decimal

Calculates the base b log of val.

+		Immutable
log(b: float, x: float) → float

Calculates the base b log of val.

+		Immutable
log(val: decimal) → decimal

Calculates the base 10 log of val.

+		Immutable
log(val: float) → float

Calculates the base 10 log of val.

+		Immutable
mod(x: decimal, y: decimal) → decimal

Calculates x%y.

+		Immutable
mod(x: float, y: float) → float

Calculates x%y.

+		Immutable
mod(x: int, y: int) → int

Calculates x%y.

+		Immutable
pi() → float

Returns the value for pi (3.141592653589793).

+		Immutable
pow(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
pow(x: float, y: float) → float

Calculates x^y.

+		Immutable
pow(x: int, y: int) → int

Calculates x^y.

+		Immutable
power(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
power(x: float, y: float) → float

Calculates x^y.

+		Immutable
power(x: int, y: int) → int

Calculates x^y.

+		Immutable
radians(val: float) → float

Converts val as a degree value to a radians value.

+		Immutable
random() → float

Returns a random floating-point number between 0 (inclusive) and 1 (exclusive). Note that the value contains at most 53 bits of randomness.

+		Volatile
round(input: decimal, decimal_accuracy: int) → decimal

Keeps decimal_accuracy number of figures to the right of the zero position in input using half away from zero rounding. If decimal_accuracy is not in the range -2^31…(2^31-1), the results are undefined.

+		Immutable
round(input: float, decimal_accuracy: int) → float

Keeps decimal_accuracy number of figures to the right of the zero position in input using half to even (banker’s) rounding.

+		Immutable
round(val: decimal) → decimal

Rounds val to the nearest integer, half away from zero: round(+/-2.4) = +/-2, round(+/-2.5) = +/-3.

+		Immutable
round(val: float) → float

Rounds val to the nearest integer using half to even (banker’s) rounding.

+		Immutable
setseed(seed: float) → void

Sets the seed for subsequent random() calls in this session (value between -1.0 and 1.0, inclusive). There are no guarantees as to how this affects the seed of random() calls that appear in the same query as setseed().

+		Volatile
sign(val: decimal) → decimal

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: float) → float

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: int) → int

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sin(val: float) → float

Calculates the sine of val.

+		Immutable
sind(val: float) → float

Calculates the sine of val where val is in degrees.

+		Immutable
sinh(val: float) → float

Calculates the hyperbolic sine of val.

+		Immutable
sqrt(val: decimal) → decimal

Calculates the square root of val.

+		Immutable
sqrt(val: float) → float

Calculates the square root of val.

+		Immutable
tan(val: float) → float

Calculates the tangent of val.

+		Immutable
tand(val: float) → float

Calculates the tangent of val where val is in degrees.

+		Immutable
tanh(val: float) → float

Calculates the hyperbolic tangent of val.

+		Immutable
trunc(val: decimal) → decimal

Truncates the decimal values of val.

+		Immutable
trunc(val: decimal, scale: int) → decimal

Truncate val to scale decimal places

+		Immutable
trunc(val: float) → float

Truncates the decimal values of val.

+		Immutable
+ +### Full Text Search functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
phraseto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The <-> operator is inserted between each token in the input.

+		Immutable
phraseto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The <-> operator is inserted between each token in the input.

+		Stable
plainto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The & operator is inserted between each token in the input.

+		Immutable
plainto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The & operator is inserted between each token in the input.

+		Stable
to_tsquery(config: string, text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the specified configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Immutable
to_tsquery(text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the default configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Stable
to_tsvector(config: string, text: string) → tsvector

Converts text to a tsvector, normalizing words according to the specified configuration. Position information is included in the result.

+		Immutable
to_tsvector(text: string) → tsvector

Converts text to a tsvector, normalizing words according to the default configuration. Position information is included in the result.

+		Stable
ts_parse(parser_name: string, document: string) → tuple{int AS tokid, string AS token}

ts_parse parses the given document and returns a series of records, one for each token produced by parsing. Each record includes a tokid showing the assigned token type and a token which is the text of the token.

+		Stable
ts_rank(vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
+ +### Fuzzy String Matching functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
levenshtein(source: string, target: string) → int

Calculates the Levenshtein distance between two strings. Maximum input length is 255 characters.

+		Immutable
levenshtein(source: string, target: string, ins_cost: int, del_cost: int, sub_cost: int) → int

Calculates the Levenshtein distance between two strings. The cost parameters specify how much to charge for each edit operation. Maximum input length is 255 characters.

+		Immutable
metaphone(source: string, max_output_length: int) → string

Convert a string to its Metaphone code. Maximum input length is 255 characters

+		Immutable
soundex(source: string) → string

Convert a string to its Soundex code.

+		Immutable
+ +### ID generation functions + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
experimental_uuid_v4() → bytes

Returns a UUID.

+		Volatile
gen_random_ulid() → uuid

Generates a random ULID and returns it as a value of UUID type.

+		Volatile
gen_random_uuid() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
unique_rowid() → int

Returns a unique ID used by CockroachDB to generate unique row IDs if a Primary Key isn’t defined for the table. The value is a combination of the insert timestamp and the ID of the node executing the statement, which guarantees this combination is globally unique. However, there can be gaps and the order is not completely guaranteed.

+		Volatile
unordered_unique_rowid() → int

Returns a unique ID. The value is a combination of the insert timestamp (bit-reversed) and the ID of the node executing the statement, which guarantees this combination is globally unique. The way it is generated is statistically likely to not have any ordering relative to previously generated values.

+		Volatile
uuid_generate_v1() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. To avoid exposing the server’s real MAC address, this uses a random MAC address and a timestamp. Essentially, this is an alias for uuid_generate_v1mc.

+		Volatile
uuid_generate_v1mc() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. This uses a random MAC address and a timestamp.

+		Volatile
uuid_generate_v3(namespace: uuid, name: string) → uuid

Generates a version 3 UUID in the given namespace using the specified input name, with md5 as the hashing method. The namespace should be one of the special constants produced by the uuid_ns_*() functions.

+		Immutable
uuid_generate_v4() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
uuid_generate_v5(namespace: uuid, name: string) → uuid

Generates a version 5 UUID in the given namespace using the specified input name. This is similar to a version 3 UUID, except it uses SHA-1 for hashing.

+		Immutable
uuid_nil() → uuid

Returns a nil UUID constant.

+		Immutable
uuid_ns_dns() → uuid

Returns a constant designating the DNS namespace for UUIDs.

+		Immutable
uuid_ns_oid() → uuid

Returns a constant designating the ISO object identifier (OID) namespace for UUIDs. These are unrelated to the OID type used internally in the database.

+		Immutable
uuid_ns_url() → uuid

Returns a constant designating the URL namespace for UUIDs.

+		Immutable
uuid_ns_x500() → uuid

Returns a constant designating the X.500 distinguished name (DN) namespace for UUIDs.

+		Immutable
uuid_v4() → bytes

Returns a UUID.

+		Volatile
+ +### INET functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abbrev(val: inet) → string

Converts the combined IP address and prefix length to an abbreviated display format as text.For INET types, this will omit the prefix length if it’s not the default (32 or IPv4, 128 for IPv6)

+

For example, abbrev('192.168.1.2/24') returns '192.168.1.2/24'

+		Immutable
broadcast(val: inet) → inet

Gets the broadcast address for the network address represented by the value.

+

For example, broadcast('192.168.1.2/24') returns '192.168.1.255/24'

+		Immutable
family(val: inet) → int

Extracts the IP family of the value; 4 for IPv4, 6 for IPv6.

+

For example, family('::1') returns 6

+		Immutable
host(val: inet) → string

Extracts the address part of the combined address/prefixlen value as text.

+

For example, host('192.168.1.2/16') returns '192.168.1.2'

+		Immutable
hostmask(val: inet) → inet

Creates an IP host mask corresponding to the prefix length in the value.

+

For example, hostmask('192.168.1.2/16') returns '0.0.255.255'

+		Immutable
masklen(val: inet) → int

Retrieves the prefix length stored in the value.

+

For example, masklen('192.168.1.2/16') returns 16

+		Immutable
netmask(val: inet) → inet

Creates an IP network mask corresponding to the prefix length in the value.

+

For example, netmask('192.168.1.2/16') returns '255.255.0.0'

+		Immutable
set_masklen(val: inet, prefixlen: int) → inet

Sets the prefix length of val to prefixlen.

+

For example, set_masklen('192.168.1.2', 16) returns '192.168.1.2/16'.

+		Immutable
+ +### INT functions + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crc32c(bytes...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32c(string...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32ieee(bytes...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
crc32ieee(string...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
fnv32(bytes...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32(string...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32a(bytes...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv32a(string...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64(bytes...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64(string...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64a(bytes...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64a(string...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
width_bucket(operand: decimal, b1: decimal, b2: decimal, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2. Returns 0 or count+1 for an input outside that range.

+		Immutable
width_bucket(operand: int, b1: int, b2: int, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2.

+		Immutable
width_bucket(operand: anyelement, thresholds: anyelement[]) → int

return the bucket number to which operand would be assigned given an array listing the lower bounds of the buckets; returns 0 for an input less than the first lower bound; the thresholds array must be sorted, smallest first, or unexpected results will be obtained

+		Immutable
+ +### JSONB functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_to_json(array: anyelement[]) → jsonb

Returns the array as JSON or JSONB.

+		Stable
array_to_json(array: anyelement[], pretty_bool: bool) → jsonb

Returns the array as JSON or JSONB.

+		Stable
json_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
json_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
json_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
json_build_array(any...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
json_build_object(any...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
json_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
json_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
json_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
json_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
json_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
json_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
json_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
json_remove_path(val: jsonb, path: string[]) → jsonb

Remove the specified path from the JSON object.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
json_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
json_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
json_valid(string: string) → bool

Returns whether the given string is a valid JSON or not

+		Immutable
jsonb_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
jsonb_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
jsonb_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
jsonb_build_array(any...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
jsonb_build_object(any...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
jsonb_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
jsonb_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
jsonb_exists_any(json: jsonb, array: string[]) → bool

Returns whether any of the strings in the text array exist as top-level keys or array elements

+		Immutable
jsonb_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments. new_val will be inserted before path target.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb, insert_after: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If insert_after is true (default is false), new_val will be inserted after path target.

+		Immutable
jsonb_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
jsonb_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
jsonb_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
jsonb_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
jsonb_pretty(val: jsonb) → string

Returns the given JSON value as a STRING indented and with newlines.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
jsonb_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
jsonb_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
row_to_json(row: tuple) → jsonb

Returns the row as a JSON object.

+		Stable
to_json(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
to_jsonb(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
+ +### Jsonpath functions + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
jsonb_path_exists(target: jsonb, path: jsonpath) → bool

Checks whether the JSON path returns any item for the specified JSON value.

+		Immutable
jsonb_path_exists(target: jsonb, path: jsonpath, vars: jsonb) → bool

Checks whether the JSON path returns any item for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named +values to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_exists(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → bool

Checks whether the JSON path returns any item for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named +values to be substituted into the jsonpath expression. If the silent +argument is true, the function suppresses the following errors: +missing object field or array element, unexpected JSON item type, +datetime and numeric errors.

+		Immutable
jsonb_path_match(target: jsonb, path: jsonpath) → bool

Returns the SQL boolean result of a JSON path predicate check +for the specified JSON value. (This is useful only with predicate check +expressions, not SQL-standard JSON path expressions, since it will +either fail or return NULL if the path result is not a single boolean +value.)

+		Immutable
jsonb_path_match(target: jsonb, path: jsonpath, vars: jsonb) → bool

Returns the SQL boolean result of a JSON path predicate check +for the specified JSON value. (This is useful only with predicate check +expressions, not SQL-standard JSON path expressions, since it will +either fail or return NULL if the path result is not a single boolean +value.) The vars argument must be a JSON object, and its fields provide +named values to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_match(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → bool

Returns the SQL boolean result of a JSON path predicate check +for the specified JSON value. (This is useful only with predicate check +expressions, not SQL-standard JSON path expressions, since it will +either fail or return NULL if the path result is not a single boolean +value.) The vars argument must be a JSON object, and its fields provide +named values to be substituted into the jsonpath expression. If the +silent argument is true, the function suppresses the following errors: +missing object field or array element, unexpected JSON item type, +datetime and numeric errors.

+		Immutable
jsonb_path_query(target: jsonb, path: jsonpath) → jsonb

Returns all JSON items returned by the JSON path for the specified JSON value.

+		Immutable
jsonb_path_query(target: jsonb, path: jsonpath, vars: jsonb) → jsonb

Returns all JSON items returned by the JSON path for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_query(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → jsonb

Returns all JSON items returned by the JSON path for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression. If the silent argument is true, +the function suppresses the following errors: missing object field or array +element, unexpected JSON item type, datetime and numeric errors.

+		Immutable
jsonb_path_query_array(target: jsonb, path: jsonpath) → jsonb

Returns all JSON items returned by the JSON path for the +specified JSON value, as a JSON array.

+		Immutable
jsonb_path_query_array(target: jsonb, path: jsonpath, vars: jsonb) → jsonb

Returns all JSON items returned by the JSON path for the +specified JSON value, as a JSON array. The vars argument must be a +JSON object, and its fields provide named values to be substituted +into the jsonpath expression.

+		Immutable
jsonb_path_query_array(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → jsonb

Returns all JSON items returned by the JSON path for the +specified JSON value, as a JSON array. The vars argument must be a +JSON object, and its fields provide named values to be substituted +into the jsonpath expression. If the silent argument is true, the +function suppresses the following errors: missing object field or +array element, unexpected JSON item type, datetime and numeric errors.

+		Immutable
jsonb_path_query_first(target: jsonb, path: jsonpath) → jsonb

Returns the first JSON item returned by the JSON path for the +specified JSON value, or NULL if there are no results.

+		Immutable
jsonb_path_query_first(target: jsonb, path: jsonpath, vars: jsonb) → jsonb

Returns the first JSON item returned by the JSON path for the +specified JSON value, or NULL if there are no results. The vars +argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_query_first(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → jsonb

Returns the first JSON item returned by the JSON path for the +specified JSON value, or NULL if there are no results. The vars +argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression. If the silent argument is true, the +function suppresses the following errors: missing object field or +array element, unexpected JSON item type, datetime and numeric errors.

+		Immutable
+ +### Multi-region functions + + + + + + + +
Function → ReturnsDescriptionVolatility
default_to_database_primary_region(val: string) → string

Returns the given region if the region has been added to the current database. +Otherwise, this will return the primary region of the current database. +This will error if the current database is not a multi-region database.

+		Stable
gateway_region() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
rehome_row() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
+ +### PGVector functions + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cosine_distance(v1: vector, v2: vector) → float

Returns the cosine distance between the two vectors.

+		Immutable
inner_product(v1: vector, v2: vector) → float

Returns the inner product between the two vectors.

+		Immutable
l1_distance(v1: vector, v2: vector) → float

Returns the Manhattan distance between the two vectors.

+		Immutable
l2_distance(v1: vector, v2: vector) → float

Returns the Euclidean distance between the two vectors.

+		Immutable
vector_dims(vector: vector) → int

Returns the number of the dimensions in the vector.

+		Immutable
vector_norm(vector: vector) → float

Returns the Euclidean norm of the vector.

+		Immutable
+ +### STRING[] functions + + + + + + +
Function → ReturnsDescriptionVolatility
regexp_split_to_array(string: string, pattern: string) → string[]

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_array(string: string, pattern: string, flags: string) → string[]

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
+ +### Sequence functions + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
currval(sequence_name: string) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
currval(sequence_name: regclass) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
lastval() → int

Return value most recently obtained with nextval in this session.

+		Volatile
nextval(sequence_name: string) → int

Advances the given sequence and returns its new value.

+		Volatile
nextval(sequence_name: regclass) → int

Advances the given sequence and returns its new value.

+		Volatile
setval(sequence_name: string, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: string, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
setval(sequence_name: regclass, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: regclass, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
+ +### Set-returning functions + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
aclexplode(aclitems: string[]) → tuple{oid AS grantor, oid AS grantee, string AS privilege_type, bool AS is_grantable}

Produces a virtual table containing aclitem stuff (returns no rows as this feature is unsupported in CockroachDB)

+		Stable
generate_series(start: int, end: int) → int

Produces a virtual table containing the integer values from start to end, inclusive.

+		Immutable
generate_series(start: int, end: int, step: int) → int

Produces a virtual table containing the integer values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamp, end: timestamp, step: interval) → timestamp

Produces a virtual table containing the timestamp values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamptz, end: timestamptz, step: interval) → timestamptz

Produces a virtual table containing the timestampTZ values from start to end, inclusive, by increment of step.

+		Immutable
generate_subscripts(array: anyelement[]) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int, reverse: bool) → int

Returns a series comprising the given array’s subscripts.

+

When reverse is true, the series is returned in reverse order.

+		Immutable
information_schema._pg_expandarray(input: anyelement[]) → tuple{anyelement AS x, int AS n}

Returns the input array as a set of rows with an index

+		Immutable
json_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
json_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
json_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
jsonb_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
jsonb_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
jsonb_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
pg_get_keywords() → tuple{string AS word, string AS catcode, string AS catdesc}

Produces a virtual table containing the keywords known to the SQL parser.

+		Immutable
pg_options_to_table(options: string[]) → tuple{string AS option_name, string AS option_value}

Converts the options array format to a table.

+		Stable
regexp_split_to_table(string: string, pattern: string) → string

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_table(string: string, pattern: string, flags: string) → string

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
unnest(anyelement[], anyelement[], anyelement[]...) → tuple{anyelement AS unnest, anyelement AS unnest, anyelement AS unnest}

Returns the input arrays as a set of rows

+		Immutable
unnest(input: anyelement[]) → anyelement

Returns the input array as a set of rows

+		Immutable
workload_index_recs() → tuple{string AS index_rec, bytes[] AS fingerprint_ids}

Returns index recommendations and the fingerprint ids that the indexes will impact

+		Immutable
workload_index_recs(timestamptz: timestamptz) → tuple{string AS index_rec, bytes[] AS fingerprint_ids}

Returns index recommendations and the fingerprint ids that the indexes will impact

+		Immutable
+ +### Spatial functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
_st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
geometrytype(geometry: geometry) → string

Returns the type of geometry as a string.

+

This function utilizes the GEOS module.

+		Immutable
geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
postgis_addbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_dropbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_extensions_upgrade() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_full_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_geos_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_getbbox(geometry: geometry) → box2d

Returns a box2d encapsulating the given Geometry.

+		Immutable
postgis_hasbbox(geometry: geometry) → bool

Returns whether a given Geometry has a bounding box. False for points and empty geometries; always true otherwise.

+		Immutable
postgis_lib_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_lib_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_liblwgeom_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_libxml_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_proj_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_installed() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_released() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_wagyu_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
st_addmeasure(geometry: geometry, start: float, end: float) → geometry

Returns a copy of a LineString or MultiLineString with measure coordinates linearly interpolated between the specified start and end values. Any existing M coordinates will be overwritten.

+		Immutable
st_addpoint(line_string: geometry, point: geometry) → geometry

Adds a Point to the end of a LineString.

+		Immutable
st_addpoint(line_string: geometry, point: geometry, index: int) → geometry

Adds a Point to a LineString at the given 0-based index (-1 to append).

+		Immutable
st_affine(geometry: geometry, a: float, b: float, c: float, d: float, e: float, f: float, g: float, h: float, i: float, x_off: float, y_off: float, z_off: float) → geometry

Applies a 3D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b c x_off \ / x
+| d e f y_off | | y | +| g h i z_off | | z | +\ 0 0 0 1 / \ 0 /

+		Immutable
st_affine(geometry: geometry, a: float, b: float, d: float, e: float, x_off: float, y_off: float) → geometry

Applies a 2D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b x_off \ / x
+| d e y_off | | y | +\ 0 0 1 / \ 0 /

+		Immutable
st_angle(line1: geometry, line2: geometry) → float

Returns the clockwise angle between two LINESTRING geometries, treating them as vectors between their start- and endpoints. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry) → float

Returns the clockwise angle between the vectors formed by point2,point1 and point2,point3. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry, point4: geometry) → float

Returns the clockwise angle between the vectors formed by point1,point2 and point3,point4. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_area(geography: geography) → float

Returns the area of the given geography in meters^2. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geography: geography, use_spheroid: bool) → float

Returns the area of the given geography in meters^2.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_area(geometry_str: string) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_area2d(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_asbinary(geography: geography) → bytes

Returns the WKB representation of a given Geography.

+		Immutable
st_asbinary(geography: geography, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asbinary(geometry: geometry) → bytes

Returns the WKB representation of a given Geometry.

+		Immutable
st_asbinary(geometry: geometry, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asencodedpolyline(geometry: geometry) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Preserves 5 decimal places.

+		Immutable
st_asencodedpolyline(geometry: geometry, precision: int4) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+		Immutable
st_asewkb(geography: geography) → bytes

Returns the EWKB representation of a given Geography.

+		Immutable
st_asewkb(geometry: geometry) → bytes

Returns the EWKB representation of a given Geometry.

+		Immutable
st_asewkt(geography: geography) → string

Returns the EWKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_asewkt(geography: geography, max_decimal_digits: int) → string

Returns the EWKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry: geometry) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_asewkt(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry_str: string) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asewkt(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geography: geography) → string

Returns the GeoJSON representation of a given Geography. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option (default for Geography)
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326
    • +
+		Immutable
st_asgeojson(geometry: geometry) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+		Immutable
st_asgeojson(geometry_str: string) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(row: tuple) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(row: tuple, geo_column: string) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. Coordinates have a maximum of 9 decimal digits.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int, pretty: bool) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value. Output will be pretty printed in JSON if pretty is true.

+		Stable
st_ashexewkb(geography: geography) → string

Returns the EWKB representation in hex of a given Geography.

+		Immutable
st_ashexewkb(geography: geography, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexewkb(geometry: geometry) → string

Returns the EWKB representation in hex of a given Geometry.

+		Immutable
st_ashexewkb(geometry: geometry, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexwkb(geography: geography) → string

Returns the WKB representation in hex of a given Geography.

+		Immutable
st_ashexwkb(geometry: geometry) → string

Returns the WKB representation in hex of a given Geometry.

+		Immutable
st_askml(geography: geography) → string

Returns the KML representation of a given Geography.

+		Immutable
st_askml(geometry: geometry) → string

Returns the KML representation of a given Geometry.

+		Immutable
st_askml(geometry_str: string) → string

Returns the KML representation of a given Geometry.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping. +Uses 4096 as the tile extent size in tile coordinate space.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int, clip: bool) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds if required.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry can be transformed, and clipped if required.

+		Immutable
st_astext(geography: geography) → string

Returns the WKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_astext(geography: geography, max_decimal_digits: int) → string

Returns the WKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry: geometry) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_astext(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry_str: string) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astext(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int, precision_m: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_azimuth(geography_a: geography, geography_b: geography) → float

Returns the azimuth in radians of the segment defined by the given point geographies, or NULL if the two points are coincident. It is solved using the Inverse geodesic problem.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_azimuth(geometry_a: geometry, geometry_b: geometry) → float

Returns the azimuth in radians of the segment defined by the given point geometries, or NULL if the two points are coincident.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+		Immutable
st_bdpolyfromtext(str: string, srid: int) → geometry

Returns a Polygon from multilinestring WKT with a SRID. If the input is not a multilinestring an error will be thrown.

+		Immutable
st_boundary(geometry: geometry) → geometry

Returns the closure of the combinatorial boundary of this Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_box2dfromgeohash(geohash: string) → box2d

Return a Box2D from a GeoHash string with max precision.

+		Immutable
st_box2dfromgeohash(geohash: string, precision: int) → box2d

Return a Box2D from a GeoHash string with supplied precision.

+		Immutable
st_buffer(geography: geography, distance: float) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, buffer_style_params: string) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, quad_segs: int) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geometry: geometry, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry_str: string, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_centroid(geography: geography) → geography

Returns the centroid of given geography. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geography: geography, use_spheroid: bool) → geography

Returns the centroid of given geography.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geometry: geometry) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_centroid(geometry_str: string) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_clipbybox2d(geometry: geometry, box2d: box2d) → geometry

Clips the geometry to conform to the bounding box specified by box2d.

+		Immutable
st_closestpoint(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the 2-dimensional point on geometry_a that is closest to geometry_b. This is the first point of the shortest line.

+		Immutable
st_collectionextract(geometry: geometry, type: int) → geometry

Given a collection, returns a multitype consisting only of elements of the specified type. If there are no elements of the given type, an EMPTY geometry is returned. Types are specified as 1=POINT, 2=LINESTRING, 3=POLYGON - other types are not supported.

+		Immutable
st_collectionhomogenize(geometry: geometry) → geometry

Returns the “simplest” representation of a collection’s contents. Collections of a single type will be returned as an appopriate multitype, or a singleton if it only contains a single geometry.

+		Immutable
st_combinebbox(box2d: box2d, geometry: geometry) → box2d

Combines the current bounding box with the bounding box of the Geometry.

+		Immutable
st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_convexhull(geometry: geometry) → geometry

Returns a geometry that represents the Convex Hull of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_coorddim(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_difference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the difference of two Geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_dimension(geometry: geometry) → int

Returns the number of topological dimensions of a given Geometry.

+		Immutable
st_disjoint(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a does not overlap, touch or is within geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_distance(geography_a: geography, geography_b: geography) → float

Returns the distance in meters between geography_a and geography_b. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geography_a: geography, geography_b: geography, use_spheroid: bool) → float

Returns the distance in meters between geography_a and geography_b.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance between the given geometries.

+		Immutable
st_distance(geometry_a_str: string, geometry_b_str: string) → float

Returns the distance between the given geometries.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_distancesphere(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_distancespheroid(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a spheroid.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_endpoint(geometry: geometry) → geometry

Returns the last point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_envelope(box2d: box2d) → geometry

Returns a bounding geometry for the given box.

+		Immutable
st_envelope(geometry: geometry) → geometry

Returns a bounding envelope for the given geometry.

+

For geometries which have a POINT or LINESTRING bounding box (i.e. is a single point +or a horizontal or vertical line), a POINT or LINESTRING is returned. Otherwise, the +returned POLYGON will be ordered Bottom Left, Top Left, Top Right, Bottom Right, +Bottom Left.

+		Immutable
st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string, parent_only: bool) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+

The parent_only boolean is always ignored.

+		Stable
st_estimatedextent(table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_expand(box2d: box2d, delta: float) → box2d

Extends the box2d by delta units across all dimensions.

+		Immutable
st_expand(box2d: box2d, delta_x: float, delta_y: float) → box2d

Extends the box2d by delta_x units in the x dimension and delta_y units in the y dimension.

+		Immutable
st_expand(geometry: geometry, delta: float) → geometry

Extends the bounding box represented by the geometry by delta units across all dimensions, returning a Polygon representing the new bounding box.

+		Immutable
st_expand(geometry: geometry, delta_x: float, delta_y: float) → geometry

Extends the bounding box represented by the geometry by delta_x units in the x dimension and delta_y units in the y dimension, returning a Polygon representing the new bounding box.

+		Immutable
st_exteriorring(geometry: geometry) → geometry

Returns the exterior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon.

+		Immutable
st_flipcoordinates(geometry: geometry) → geometry

Returns a new geometry with the X and Y axes flipped.

+		Immutable
st_force2d(geometry: geometry) → geometry

Returns a Geometry that is forced into XY layout with any Z or M dimensions discarded.

+		Immutable
st_force3d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to 0. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry, defaultM: float) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to the specified default M value. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force4d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZM layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float, defaultM: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified Z value. If a M coordinate doesn’t exist, it will be set to the specified M value.

+		Immutable
st_forcecollection(geometry: geometry) → geometry

Converts the geometry into a GeometryCollection.

+		Immutable
st_forcepolygonccw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_forcepolygoncw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Frechet distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Frechet distance between the given geometries, with the given segment densification (range 0.0-1.0, -1 to disable).

+

Smaller densify_frac gives a more accurate Fréchet distance. However, the computation time and memory usage increases with the square of the number of subsegments.

+

This function utilizes the GEOS module.

+		Immutable
st_generatepoints(geometry: geometry, npoints: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. Uses system time as a seed. +The requested number of points must be not larger than 65336.

+		Volatile
st_generatepoints(geometry: geometry, npoints: int4, seed: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. +The requested number of points must be not larger than 65336.

+		Immutable
st_geogfromewkb(val: bytes) → geography

Returns the Geography from an EWKB representation.

+		Immutable
st_geogfromewkt(val: string) → geography

Returns the Geography from an EWKT representation.

+		Immutable
st_geogfromgeojson(val: string) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromgeojson(val: jsonb) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geogfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geogfromwkb(bytes: bytes, srid: int) → geography

Returns the Geography from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geogfromwkb(val: bytes) → geography

Returns the Geography from a WKB (or EWKB) representation.

+		Immutable
st_geographyfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geographyfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geohash(geography: geography) → string

Returns a GeoHash representation of the geeographywith full precision if a point is provided, or with variable precision based on the size of the feature.

+		Immutable
st_geohash(geography: geography, precision: int) → string

Returns a GeoHash representation of the geography with the supplied precision.

+		Immutable
st_geohash(geometry: geometry) → string

Returns a GeoHash representation of the geometry with full precision if a point is provided, or with variable precision based on the size of the feature. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geohash(geometry: geometry, precision: int) → string

Returns a GeoHash representation of the geometry with the supplied precision. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geomcollfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomcollfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geometryfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geometryfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geometryn(geometry: geometry, n: int) → geometry

Returns the n-th Geometry (1-indexed). Returns NULL if out of bounds.

+		Immutable
st_geometrytype(geometry: geometry) → string

Returns the type of geometry as a string prefixed with ST_.

+

This function utilizes the GEOS module.

+		Immutable
st_geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
st_geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
st_geomfromgeohash(geohash: string) → geometry

Return a POLYGON Geometry from a GeoHash string with max precision.

+		Immutable
st_geomfromgeohash(geohash: string, precision: int) → geometry

Return a POLYGON Geometry from a GeoHash string with supplied precision.

+		Immutable
st_geomfromgeojson(val: string) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromgeojson(val: jsonb) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geomfromwkb(bytes: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geomfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_hasarc(geometry: geometry) → bool

Returns whether there is a CIRCULARSTRING in the geometry.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Hausdorff distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Hausdorff distance between the given geometries, with the given segment densification (range 0.0-1.0).

+

This function utilizes the GEOS module.

+		Immutable
st_interiorringn(geometry: geometry, n: int) → geometry

Returns the n-th (1-indexed) interior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon, or the ring does not exist.

+		Immutable
st_intersection(geography_a: geography, geography_b: geography) → geography

Returns the point intersections of the given geographies.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a_str: string, geometry_b_str: string) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_isclosed(geometry: geometry) → bool

Returns whether the geometry is closed as defined by whether the start and end points are coincident. Points are considered closed, empty geometries are not. For collections and multi-types, all members must be closed, as must all polygon rings.

+		Immutable
st_iscollection(geometry: geometry) → bool

Returns whether the geometry is of a collection type (including multi-types).

+		Immutable
st_isempty(geometry: geometry) → bool

Returns whether the geometry is empty.

+		Immutable
st_ispolygonccw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are considered counter-clockwise.

+		Immutable
st_ispolygoncw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are considered clockwise.

+		Immutable
st_isring(geometry: geometry) → bool

Returns whether the geometry is a single linestring that is closed and simple, as defined by ST_IsClosed and ST_IsSimple.

+

This function utilizes the GEOS module.

+		Immutable
st_issimple(geometry: geometry) → bool

Returns true if the geometry has no anomalous geometric points, e.g. that it intersects with or lies tangent to itself.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry) → bool

Returns whether the geometry is valid as defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry, flags: int) → bool

Returns whether the geometry is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry) → string

Returns a string containing the reason the geometry is invalid along with the point of interest, or “Valid Geometry” if it is valid. Validity is defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry, flags: int) → string

Returns the reason the geometry is invalid or “Valid Geometry” if it is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidtrajectory(geometry: geometry) → bool

Returns whether the geometry encodes a valid trajectory.

+

Note the geometry must be a LineString with M coordinates.

+		Immutable
st_length(geography: geography) → float

Returns the length of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geography: geography, use_spheroid: bool) → float

Returns the length of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_length(geometry_str: string) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_length2d(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_linecrossingdirection(linestring_a: geometry, linestring_b: geometry) → int

Returns an interger value defining behavior of crossing of lines: +0: lines do not cross, +-1: linestring_b crosses linestring_a from right to left, +1: linestring_b crosses linestring_a from left to right, +-2: linestring_b crosses linestring_a multiple times from right to left, +2: linestring_b crosses linestring_a multiple times from left to right, +-3: linestring_b crosses linestring_a multiple times from left to left, +3: linestring_b crosses linestring_a multiple times from right to right.

+

Note that the top vertex of the segment touching another line does not count as a crossing, but the bottom vertex of segment touching another line is considered a crossing.

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string) → geometry

Creates a LineString from an Encoded Polyline string.

+

Returns valid results only if the polyline was encoded with 5 decimal places.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string, precision: int4) → geometry

Creates a LineString from an Encoded Polyline string.

+

Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefrommultipoint(geometry: geometry) → geometry

Creates a LineString from a MultiPoint geometry.

+		Immutable
st_linefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_lineinterpolatepoint(geometry: geometry, fraction: float) → geometry

Returns a point along the given LineString which is at given fraction of LineString’s total length.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float, repeat: bool) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length. If repeat is false (default true) then it returns first point.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_linelocatepoint(line: geometry, point: geometry) → float

Returns a float between 0 and 1 representing the location of the closest point on LineString to the given Point, as a fraction of total 2d line length.

+		Immutable
st_linemerge(geometry: geometry) → geometry

Returns a LineString or MultiLineString by joining together constituents of a MultiLineString with matching endpoints. If the input is not a MultiLineString or LineString, an empty GeometryCollection is returned.

+

This function utilizes the GEOS module.

+		Immutable
st_linestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: decimal, end_fraction: decimal) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: float, end_fraction: float) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_longestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the max distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the maximum distance between the geometry’s vertexes. The function will return the longest line that was discovered first when comparing maximum distances if more than one is found.

+		Immutable
st_m(geometry: geometry) → float

Returns the M coordinate of a geometry if it is a Point.

+		Immutable
st_makebox2d(geometry_a: geometry, geometry_b: geometry) → box2d

Creates a box2d from two points. Errors if arguments are not two non-empty points.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with SRID 0.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float, srid: int) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with the given SRID.

+		Immutable
st_makepoint(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float) → geometry

Returns a new Point with the given X, Y, and Z coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float, m: float) → geometry

Returns a new Point with the given X, Y, Z, and M coordinates.

+		Immutable
st_makepointm(x: float, y: float, m: float) → geometry

Returns a new Point with the given X, Y, and M coordinates.

+		Immutable
st_makepolygon(geometry: geometry) → geometry

Returns a new Polygon with the given outer LineString.

+		Immutable
st_makepolygon(outer: geometry, interior: anyelement[]) → geometry

Returns a new Polygon with the given outer LineString and interior (hole) LineString(s).

+		Immutable
st_makevalid(geometry: geometry) → geometry

Returns a valid form of the given geometry according to the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_maxdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the maximum distance across every pair of points comprising the given geometries. Note if the geometries are the same, it will return the maximum distance between the geometry’s vertexes.

+		Immutable
st_memsize(geometry: geometry) → int

Returns the amount of memory space (in bytes) the geometry takes.

+		Immutable
st_minimumboundingcircle(geometry: geometry) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingcircle(geometry: geometry, num_segs: int) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingradius(geometry: geometry) → tuple{geometry AS center, float AS radius}

Returns a record containing the center point and radius of the smallest circle that can fully contains the given geometry.

+		Immutable
st_minimumclearance(geometry: geometry) → float

Returns the minimum distance a vertex can move before producing an invalid geometry. Returns Infinity if no minimum clearance can be found (e.g. for a single point).

+		Immutable
st_minimumclearanceline(geometry: geometry) → geometry

Returns a LINESTRING spanning the minimum distance a vertex can move before producing an invalid geometry. If no minimum clearance can be found (e.g. for a single point), an empty LINESTRING is returned.

+		Immutable
st_mlinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mlinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mpointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multi(geometry: geometry) → geometry

Returns the geometry as a new multi-geometry, e.g converts a POINT to a MULTIPOINT. If the input is already a multitype or collection, it is returned as is.

+		Immutable
st_multilinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multipointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_ndims(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_node(geometry: geometry) → geometry

Adds a node on a geometry for each intersection. Resulting geometry is always a MultiLineString.

+		Immutable
st_normalize(geometry: geometry) → geometry

Returns the geometry in its normalized form.

+

This function utilizes the GEOS module.

+		Immutable
st_npoints(geometry: geometry) → int

Returns the number of points in a given Geometry. Works for any shape type.

+		Immutable
st_nrings(geometry: geometry) → int

Returns the number of rings in a Polygon Geometry. Returns 0 if the shape is not a Polygon.

+		Immutable
st_numgeometries(geometry: geometry) → int

Returns the number of shapes inside a given Geometry.

+		Immutable
st_numinteriorring(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numinteriorrings(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numpoints(geometry: geometry) → int

Returns the number of points in a LineString. Returns NULL if the Geometry is not a LineString.

+		Immutable
st_orderingequals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is exactly equal to geometry_b, having all coordinates in the same order, as well as the same type, SRID, bounding box, and so on.

+		Immutable
st_orientedenvelope(geometry: geometry) → geometry

Returns a minimum rotated rectangle enclosing a geometry. +Note that more than one minimum rotated rectangle may exist. +May return a Point or LineString in the case of degenerate inputs.

+		Immutable
st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_perimeter(geography: geography) → float

Returns the perimeter of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geography: geography, use_spheroid: bool) → float

Returns the perimeter of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_perimeter2d(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_point(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_pointfromgeohash(geohash: string) → geometry

Return a POINT Geometry from a GeoHash string with max precision.

+		Immutable
st_pointfromgeohash(geohash: string, precision: int) → geometry

Return a POINT Geometry from a GeoHash string with supplied precision.

+		Immutable
st_pointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Point, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_pointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointinsidecircle(geometry: geometry, x_coord: float, y_coord: float, radius: float) → bool

Returns the true if the geometry is a point and is inside the circle. Returns false otherwise.

+		Immutable
st_pointn(geometry: geometry, n: int) → geometry

Returns the n-th Point of a LineString (1-indexed). Returns NULL if out of bounds or not a LineString.

+		Immutable
st_pointonsurface(geometry: geometry) → geometry

Returns a point that intersects with the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_points(geometry: geometry) → geometry

Returns all coordinates in the given Geometry as a MultiPoint, including duplicates.

+		Immutable
st_polyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygon(geometry: geometry, srid: int) → geometry

Returns a new Polygon from the given LineString and sets its SRID. It is equivalent to ST_MakePolygon with a single argument followed by ST_SetSRID.

+		Immutable
st_polygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_project(geography: geography, distance: float, azimuth: float) → geography

Returns a point projected from a start point along a geodesic using a given distance and azimuth (bearing). +This is known as the direct geodesic problem.

+

The distance is given in meters. Negative values are supported.

+

The azimuth (also known as heading or bearing) is given in radians. It is measured clockwise from true north (azimuth zero). +East is azimuth π/2 (90 degrees); south is azimuth π (180 degrees); west is azimuth 3π/2 (270 degrees). +Negative azimuth values and values greater than 2π (360 degrees) are supported.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, bnr: int) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b using the given boundary node rule (1:OGC/MOD2, 2:Endpoint, 3:MultivalentEndpoint, 4:MonovalentEndpoint).

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, pattern: string) → bool

Returns whether the DE-9IM spatial relation between geometry_a and geometry_b matches the DE-9IM pattern.

+

This function utilizes the GEOS module.

+		Immutable
st_relatematch(intersection_matrix: string, pattern: string) → bool

Returns whether the given DE-9IM intersection matrix satisfies the given pattern.

+		Immutable
st_removepoint(line_string: geometry, index: int) → geometry

Removes the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_removerepeatedpoints(geometry: geometry) → geometry

Returns a geometry with repeated points removed.

+		Immutable
st_removerepeatedpoints(geometry: geometry, tolerance: float) → geometry

Returns a geometry with repeated points removed, within the given distance tolerance.

+		Immutable
st_reverse(geometry: geometry) → geometry

Returns a modified geometry by reversing the order of its vertices.

+		Immutable
st_rotate(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_point: geometry) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_x: float, origin_y: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotatex(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the x axis by a rotation angle.

+		Immutable
st_rotatey(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the y axis by a rotation angle.

+		Immutable
st_rotatez(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the z axis by a rotation angle.

+		Immutable
st_s2covering(geography: geography) → geography

Returns a geography which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geography: geography, settings: string) → geography

Returns a geography which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geography, 's2_max_level=15,s2_level_mod=3').

+		Immutable
st_s2covering(geometry: geometry) → geometry

Returns a geometry which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geometry: geometry, settings: string) → geometry

Returns a geometry which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geometry, 's2_max_level=15,s2_level_mod=3')

+		Immutable
st_scale(g: geometry, factor: geometry) → geometry

Returns a modified Geometry scaled by taking in a Geometry as the factor.

+		Immutable
st_scale(g: geometry, factor: geometry, origin: geometry) → geometry

Returns a modified Geometry scaled by the Geometry factor relative to a false origin.

+		Immutable
st_scale(geometry: geometry, x_factor: float, y_factor: float) → geometry

Returns a modified Geometry scaled by the given factors.

+		Immutable
st_segmentize(geography: geography, max_segment_length_meters: float) → geography

Returns a modified Geography having no segment longer than the given max_segment_length meters.

+

The calculations are done on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_segmentize(geometry: geometry, max_segment_length: float) → geometry

Returns a modified Geometry having no segment longer than the given max_segment_length. Length units are in units of spatial reference.

+		Immutable
st_setpoint(line_string: geometry, index: int, point: geometry) → geometry

Sets the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_setsrid(geography: geography, srid: int) → geography

Sets a Geography to a new SRID without transforming the coordinates.

+		Immutable
st_setsrid(geometry: geometry, srid: int) → geometry

Sets a Geometry to a new SRID without transforming the coordinates.

+		Immutable
st_sharedpaths(geometry_a: geometry, geometry_b: geometry) → geometry

Returns a collection containing paths shared by the two input geometries.

+

Those going in the same direction are in the first element of the collection, +those going in the opposite direction are in the second element. +The paths themselves are given in the direction of the first geometry.

+		Immutable
st_shiftlongitude(geometry: geometry) → geometry

Returns a modified version of a geometry in which the longitude (X coordinate) of each point is incremented by 360 if it is <0 and decremented by 360 if it is >180. The result is only meaningful if the coordinates are in longitude/latitude.

+		Immutable
st_shortestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the minimum distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the minimum distance between the geometry’s vertexes. The function will return the shortest line that was discovered first when comparing minimum distances if more than one is found.

+		Immutable
st_simplify(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm.

+

This function utilizes the GEOS module.

+		Immutable
st_simplify(geometry: geometry, tolerance: float, preserve_collapsed: bool) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, retaining objects that would be too small given the tolerance if preserve_collapsed is set to true.

+		Immutable
st_simplifypreservetopology(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, avoiding the creation of invalid geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_snap(input: geometry, target: geometry, tolerance: float) → geometry

Snaps the vertices and segments of input geometry the target geometry’s vertices. +Tolerance is used to control where snapping is performed. The result geometry is the input geometry with the vertices snapped. +If no snapping occurs then the input geometry is returned unchanged.

+		Immutable
st_snaptogrid(geometry: geometry, origin: geometry, size_x: float, size_y: float, size_z: float, size_m: float) → geometry

Snap a geometry to a grid defined by the given origin and X, Y, Z, and M cell sizes. Any dimension with a 0 cell size will not be snapped.

+		Immutable
st_snaptogrid(geometry: geometry, origin_x: float, origin_y: float, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y based on an origin of (origin_x, origin_y).

+		Immutable
st_snaptogrid(geometry: geometry, size: float) → geometry

Snap a geometry to a grid of the given size. The specified size is only used to snap X and Y coordinates.

+		Immutable
st_snaptogrid(geometry: geometry, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y.

+		Immutable
st_srid(geography: geography) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geography as defined in spatial_ref_sys table.

+		Immutable
st_srid(geometry: geometry) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geometry as defined in spatial_ref_sys table.

+		Immutable
st_startpoint(geometry: geometry) → geometry

Returns the first point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_subdivide(geometry: geometry) → geometry

Returns a geometry divided into parts, where each part contains no more than 256 vertices.

+		Immutable
st_subdivide(geometry: geometry, max_vertices: int4) → geometry

Returns a geometry divided into parts, where each part contains no more than the number of vertices provided.

+		Immutable
st_summary(geography: geography) → string

Returns a text summary of the contents of the geography.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_summary(geometry: geometry) → string

Returns a text summary of the contents of the geometry.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_swapordinates(geometry: geometry, swap_ordinate_string: string) → geometry

Returns a version of the given geometry with given ordinates swapped. +The swap_ordinate_string parameter is a 2-character string naming the ordinates to swap. Valid names are: x, y, z and m.

+		Immutable
st_symdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_symmetricdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4, bounds: geometry) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4, bounds: geometry, margin: float) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, srid: int) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates. The supplied SRID is set on the new geometry.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, srid: int) → geometry

Transforms a geometry into the given SRID coordinate reference system by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system referenced by the projection text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float, delta_z: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_transscale(geometry: geometry, delta_x: float, delta_y: float, x_factor: float, y_factor: float) → geometry

Translates the geometry using the deltaX and deltaY args, then scales it using the XFactor, YFactor args, working in 2D only.

+		Immutable
st_unaryunion(geometry: geometry) → geometry

Returns a union of the components for any geometry or geometry collection provided. Dissolves boundaries of a multipolygon.

+		Immutable
st_voronoilines(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoipolygons(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_wkbtosql(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_wkttosql(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_x(geometry: geometry) → float

Returns the X coordinate of a geometry if it is a Point.

+		Immutable
st_xmax(box2d: box2d) → float

Returns the maximum X ordinate of a box2d.

+		Immutable
st_xmax(geometry: geometry) → float

Returns the maximum X ordinate of a geometry.

+		Immutable
st_xmin(box2d: box2d) → float

Returns the minimum X ordinate of a box2d.

+		Immutable
st_xmin(geometry: geometry) → float

Returns the minimum X ordinate of a geometry.

+		Immutable
st_y(geometry: geometry) → float

Returns the Y coordinate of a geometry if it is a Point.

+		Immutable
st_ymax(box2d: box2d) → float

Returns the maximum Y ordinate of a box2d.

+		Immutable
st_ymax(geometry: geometry) → float

Returns the maximum Y ordinate of a geometry.

+		Immutable
st_ymin(box2d: box2d) → float

Returns the minimum Y ordinate of a box2d.

+		Immutable
st_ymin(geometry: geometry) → float

Returns the minimum Y ordinate of a geometry.

+		Immutable
st_z(geometry: geometry) → float

Returns the Z coordinate of a geometry if it is a Point.

+		Immutable
st_zmflag(geometry: geometry) → int2

Returns a code based on the ZM coordinate dimension of a geometry (XY = 0, XYM = 1, XYZ = 2, XYZM = 3).

+		Immutable
+ +### String and byte functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ascii(val: string) → int

Returns the character code of the first character in val. Despite the name, the function supports Unicode too.

+		Immutable
bit_count(val: bytes) → int

Calculates the number of bits set used to represent val.

+		Immutable
bit_count(val: varbit) → int

Calculates the number of bits set used to represent val.

+		Immutable
bit_length(val: bytes) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: string) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
bitmask_and(a: string, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: string, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
btrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning or end of input (applies recursively).

+

For example, btrim('doggie', 'eod') returns ggi.

+		Immutable
btrim(val: string) → string

Removes all spaces from the beginning and end of val.

+		Immutable
char_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
char_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
character_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
character_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
chr(val: int) → string

Returns the character with the code given in val. Inverse function of ascii().

+		Immutable
compress(data: bytes, codec: string) → bytes

Compress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
concat(any...) → string

Concatenates a comma-separated list of strings.

+		Immutable
concat_ws(string, any...) → string

Uses the first argument as a separator between the concatenation of the subsequent arguments.

+

For example concat_ws('!','wow','great') returns wow!great.

+		Immutable
convert_from(str: bytes, enc: string) → string

Decode the bytes in str into a string using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
convert_to(str: string, enc: string) → bytes

Encode the string str as a byte array using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
decode(text: string, format: string) → bytes

Decodes data using format (hex / escape / base64).

+		Immutable
decompress(data: bytes, codec: string) → bytes

Decompress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
difference(source: string, target: string) → int

Convert two strings to their Soundex codes and report the number of matching code positions.

+		Immutable
encode(data: bytes, format: string) → string

Encodes data using format (hex / escape / base64).

+		Immutable
format(string, any...) → string

Interprets the first argument as a format string similar to C sprintf and interpolates the remaining arguments.

+		Stable
from_ip(val: bytes) → string

Converts the byte string representation of an IP to its character string representation.

+		Immutable
from_uuid(val: bytes) → string

Converts the byte string representation of a UUID to its character string representation.

+		Immutable
get_bit(bit_string: varbit, index: int) → int

Extracts a bit at given index in the bit array.

+		Immutable
get_bit(byte_string: bytes, index: int) → int

Extracts a bit at the given index in the byte array.

+		Immutable
get_byte(byte_string: bytes, index: int) → int

Extracts a byte at the given index in the byte array.

+		Immutable
initcap(val: string) → string

Capitalizes the first letter of val.

+		Immutable
left(input: bytes, return_set: int) → bytes

Returns the first return_set bytes from input.

+		Immutable
left(input: string, return_set: int) → string

Returns the first return_set characters from input.

+		Immutable
length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
length(val: string) → int

Calculates the number of characters in val.

+		Immutable
length(val: varbit) → int

Calculates the number of bits in val.

+		Immutable
lower(val: string) → string

Converts all characters in val to their lower-case equivalents.

+		Immutable
lpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the left of string.If string is longer than length it is truncated.

+		Immutable
lpad(string: string, length: int, fill: string) → string

Pads string by adding fill to the left of string to make it length. If string is longer than length it is truncated.

+		Immutable
ltrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning (left-hand side) of input (applies recursively).

+

For example, ltrim('doggie', 'od') returns ggie.

+		Immutable
ltrim(val: string) → string

Removes all spaces from the beginning (left-hand side) of val.

+		Immutable
md5(bytes...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
md5(string...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
octet_length(val: bytes) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: string) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int) → string

Replaces characters in input with overlay_val starting at start_pos (begins at 1).

+

For example, overlay('doggie', 'CAT', 2) returns dCATie.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int, end_pos: int) → string

Deletes the characters in input between start_pos and end_pos (count starts at 1), and then insert overlay_val at start_pos.

+		Immutable
parse_date(string: string, datestyle: string) → date

Parses a date assuming it is in format specified by DateStyle.

+		Immutable
parse_date(val: string) → date

Parses a date assuming it is in MDY format.

+		Immutable
parse_ident(qualified_identifier: string) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. Extra characters after the last identifier are considered an error

+		Immutable
parse_ident(qualified_identifier: string, strict: bool) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. If strict is false, then extra characters after the last identifier are ignored.

+		Immutable
parse_interval(string: string, style: string) → interval

Convert a string to an interval using the given IntervalStyle.

+		Immutable
parse_interval(val: string) → interval

Convert a string to an interval assuming the Postgres IntervalStyle.

+		Immutable
parse_time(string: string, timestyle: string) → time

Parses a time assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_time(val: string) → time

Parses a time assuming the date (if any) is in MDY format.

+		Immutable
parse_timestamp(string: string, datestyle: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates formatted using the given DateStyle.

+		Immutable
parse_timestamp(val: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates are in MDY format.

+		Immutable
parse_timetz(string: string, timestyle: string) → timetz

Parses a timetz assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_timetz(val: string) → timetz

Parses a timetz assuming the date (if any) is in MDY format.

+		Immutable
prettify_statement(statement: string, line_width: int, align_mode: int, case_mode: int) → string

Prettifies a statement using a user-configured pretty-printing config. +Align mode values range from 0 - 3, representing no, partial, full, and extra alignment respectively. +Case mode values range between 0 - 1, representing lower casing and upper casing respectively.

+		Immutable
prettify_statement(val: string) → string

Prettifies a statement using a the default pretty-printing config.

+		Immutable
quote_ident(val: string) → string

Return val suitably quoted to serve as identifier in a SQL statement.

+		Immutable
quote_literal(val: string) → string

Return val suitably quoted to serve as string literal in a SQL statement.

+		Immutable
quote_literal(val: anyelement) → string

Coerce val to a string and then quote it as a literal.

+		Stable
quote_nullable(val: string) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Immutable
quote_nullable(val: anyelement) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Stable
regexp_extract(input: string, regex: string) → string

Returns the first match for the Regular Expression regex in input.

+		Immutable
regexp_replace(input: string, regex: string, replace: string) → string

Replaces matches for the Regular Expression regex in input with the Regular Expression replace.

+		Immutable
regexp_replace(input: string, regex: string, replace: string, flags: string) → string

Replaces matches for the regular expression regex in input with the regular expression replace using flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
repeat(input: string, repeat_counter: int) → string

Concatenates input repeat_counter number of times.

+

For example, repeat('dog', 2) returns dogdog.

+		Immutable
replace(input: string, find: string, replace: string) → string

Replaces all occurrences of find with replace in input

+		Immutable
reverse(val: string) → string

Reverses the order of the string’s characters.

+		Immutable
right(input: bytes, return_set: int) → bytes

Returns the last return_set bytes from input.

+		Immutable
right(input: string, return_set: int) → string

Returns the last return_set characters from input.

+		Immutable
rpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the right of string. If string is longer than length it is truncated.

+		Immutable
rpad(string: string, length: int, fill: string) → string

Pads string to length by adding fill to the right of string. If string is longer than length it is truncated.

+		Immutable
rtrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the end (right-hand side) of input (applies recursively).

+

For example, rtrim('doggie', 'ei') returns dogg.

+		Immutable
rtrim(val: string) → string

Removes all spaces from the end (right-hand side) of val.

+		Immutable
set_bit(bit_string: varbit, index: int, to_set: int) → varbit

Updates a bit at given index in the bit array.

+		Immutable
set_bit(byte_string: bytes, index: int, to_set: int) → bytes

Updates a bit at the given index in the byte array.

+		Immutable
set_byte(byte_string: bytes, index: int, to_set: int) → bytes

Updates a byte at the given index in the byte array.

+		Immutable
sha1(bytes...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha1(string...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha224(bytes...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha224(string...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha256(bytes...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha256(string...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha384(bytes...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha384(string...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha512(bytes...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
sha512(string...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
similar_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_to_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
split_part(input: string, delimiter: string, return_index_pos: int) → string

Splits input using delimiter and returns the field at return_index_pos (starting from 1). If return_index_pos is negative, it returns the |return_index_pos|'th field from the end.

+

For example, split_part('123.456.789.0', '.', 3) returns 789.

+		Immutable
strpos(input: bytes, find: bytes) → int

Calculates the position where the byte subarray find begins in input.

+		Immutable
strpos(input: string, find: string) → int

Calculates the position where the string find begins in input.

+

For example, strpos('doggie', 'gie') returns 4.

+		Immutable
strpos(input: varbit, find: varbit) → int

Calculates the position where the bit subarray find begins in input.

+		Immutable
substr(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substr(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substr(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substring(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substring(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring_index(input: string, delim: string, count: int) → string

Returns a substring of input before count occurrences of delim. +If count is positive, the leftmost part is returned. If count is negative, the rightmost part is returned.

+		Immutable
to_char_with_style(date: date, datestyle: string) → string

Convert an date to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_char_with_style(interval: interval, style: string) → string

Convert an interval to a string using the given IntervalStyle.

+		Immutable
to_char_with_style(timestamp: timestamp, datestyle: string) → string

Convert an timestamp to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_english(val: int) → string

This function enunciates the value of its argument using English cardinals.

+		Immutable
to_hex(val: bytes) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: int) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: string) → string

Converts val to its hexadecimal representation.

+		Immutable
to_ip(val: string) → bytes

Converts the character string representation of an IP to its byte string representation.

+		Immutable
to_uuid(val: string) → bytes

Converts the character string representation of a UUID to its byte string representation.

+		Immutable
translate(input: string, find: string, replace: string) → string

In input, replaces the first character from find with the first character in replace; repeat for each character in find.

+

For example, translate('doggie', 'dog', '123'); returns 1233ie.

+		Immutable
ulid_to_uuid(val: string) → uuid

Converts a ULID string to its UUID-encoded representation.

+		Immutable
unaccent(val: string) → string

Removes accents (diacritic signs) from the text provided in val.

+		Immutable
upper(val: string) → string

Converts all characters in val to their to their upper-case equivalents.

+		Immutable
+ +### System info functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cluster_logical_timestamp() → decimal

Returns the logical time of the current transaction as +a CockroachDB HLC in decimal form.

+

Note that uses of this function disable server-side optimizations and +may increase either contention or retry errors, or both.

+

Returns an error if run in a transaction with an isolation level weaker than SERIALIZABLE.

+		Volatile
current_database() → string

Returns the current database.

+		Stable
current_schema() → string

Returns the current schema.

+		Stable
current_schemas(include_pg_catalog: bool) → string[]

Returns the valid schemas in the search path.

+		Stable
current_user() → string

Returns the current user. This function is provided for compatibility with PostgreSQL.

+		Stable
session_user() → string

Returns the session user. This function is provided for compatibility with PostgreSQL.

+		Stable
to_regclass(text: string) → regtype

Translates a textual relation name to its OID

+		Stable
to_regnamespace(text: string) → regtype

Translates a textual schema name to its OID

+		Stable
to_regproc(text: string) → regtype

Translates a textual function or procedure name to its OID

+		Stable
to_regprocedure(text: string) → regtype

Translates a textual function or procedure name(with argument types) to its OID

+		Stable
to_regrole(text: string) → regtype

Translates a textual role name to its OID

+		Stable
to_regtype(text: string) → regtype

Translates a textual type name to its OID

+		Stable
version() → string

Returns the node’s version of CockroachDB.

+		Volatile
+ +### TIMETZ functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
current_time() → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time() → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_time(precision: int) → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time(precision: int) → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → timetz

Returns the current transaction’s time with time zone.

+		Stable
localtime(precision: int) → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime(precision: int) → timetz

Returns the current transaction’s time with time zone.

+		Stable
+ +### Trigrams functions + + + + + + +
Function → ReturnsDescriptionVolatility
show_trgm(input: string) → string[]

Returns an array of all the trigrams in the given string.

+		Immutable
similarity(left: string, right: string) → float

Returns a number that indicates how similar the two arguments are. The range of the result is zero (indicating that the two strings are completely dissimilar) to one (indicating that the two strings are identical).

+		Immutable
+ +### UUID functions + + + + + +
Function → ReturnsDescriptionVolatility
uuid_to_ulid(val: uuid) → string

Converts a UUID-encoded ULID to its string representation.

+		Immutable
+ +### Compatibility functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
col_description(table_oid: oid, column_number: int) → string

Returns the comment for a table column, which is specified by the OID of its table and its column number. (obj_description cannot be used for table columns, since columns do not have OIDs of their own.)

+		Stable
current_setting(setting_name: string) → string

System info

+		Stable
current_setting(setting_name: string, missing_ok: bool) → string

System info

+		Stable
format_type(type_oid: oid, typemod: int) → string

Returns the SQL name of a data type that is identified by its type OID and possibly a type modifier. Currently, the type modifier is ignored.

+		Stable
getdatabaseencoding() → string

Returns the current encoding name used by the database.

+		Stable
has_any_column_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_column_privilege(table: string, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: string, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_database_privilege(database: string, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(database: oid, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(user: string, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: string, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_foreign_data_wrapper_privilege(fdw: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(fdw: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_function_privilege(function: string, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(function: oid, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(user: string, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: string, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_language_privilege(language: string, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(language: oid, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(user: string, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: string, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_schema_privilege(schema: string, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(schema: oid, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_sequence_privilege(sequence: string, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(sequence: oid, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_server_privilege(server: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(server: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_table_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_tablespace_privilege(tablespace: string, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(tablespace: oid, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_type_privilege(type: string, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(type: oid, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(user: string, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: string, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
information_schema._pg_numeric_precision(typid: oid, typmod: int4) → int

Returns the precision of the given type with type modifier

+		Immutable
information_schema._pg_numeric_precision_radix(typid: oid, typmod: int4) → int

Returns the radix of the given type with type modifier

+		Immutable
information_schema._pg_numeric_scale(typid: oid, typmod: int4) → int

Returns the scale of the given type with type modifier

+		Immutable
nameconcatoid(name: string, oid: oid) → name

Used in the information_schema to produce specific_name columns, which are supposed to be unique per schema. The result is the same as ($1::text || ‘_’ || $2::text)::name except that, if it would not fit in 63 characters, we make it do so by truncating the name input (not the oid).

+		Immutable
obj_description(object_oid: oid) → string

Returns the comment for a database object specified by its OID alone. This is deprecated since there is no guarantee that OIDs are unique across different system catalogs; therefore, the wrong comment might be returned.

+		Stable
obj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a database object specified by its OID and the name of the containing system catalog. For example, obj_description(123456, ‘pg_class’) would retrieve the comment for the table with OID 123456.

+		Stable
oidvectortypes(vector: oidvector) → string

Generates a comma seperated string of type names from an oidvector.

+		Stable
pg_backend_pid() → int

Returns a numerical ID attached to this session. This ID is part of the query cancellation key used by the wire protocol. This function was only added for compatibility, and unlike in Postgres, the returned value does not correspond to a real process ID.

+		Stable
pg_collation_for(str: anyelement) → string

Returns the collation of the argument

+		Stable
pg_column_is_updatable(reloid: oid, attnum: int2, include_triggers: bool) → bool

Returns whether the given column can be updated.

+		Stable
pg_column_size(any...) → int

Return size in bytes of the column provided as an argument

+		Stable
pg_function_is_visible(oid: oid) → bool

Returns whether the function with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_get_function_arg_default(func_oid: oid, arg_num: int4) → string

Get textual representation of a function argument’s default value. The second argument of this function is the argument number among all arguments (i.e. proallargtypes, not proargtypes), starting with 1, because that’s how information_schema.sql uses it. Currently, this always returns NULL, since CockroachDB does not support default values.

+		Stable
pg_get_function_arguments(func_oid: oid) → string

Returns the argument list (with defaults) necessary to identify a function, in the form it would need to appear in within CREATE FUNCTION.

+		Stable
pg_get_function_identity_arguments(func_oid: oid) → string

Returns the argument list (without defaults) necessary to identify a function, in the form it would need to appear in within ALTER FUNCTION, for instance.

+		Stable
pg_get_function_result(func_oid: oid) → string

Returns the types of the result of the specified function.

+		Stable
pg_get_functiondef(func_oid: oid) → string

For user-defined functions, returns the definition of the specified function. For builtin functions, returns the name of the function.

+		Stable
pg_get_indexdef(index_oid: oid) → string

Gets the CREATE INDEX command for index

+		Stable
pg_get_indexdef(index_oid: oid, column_no: int, pretty_bool: bool) → string

Gets the CREATE INDEX command for index, or definition of just one index column when given a non-zero column number

+		Stable
pg_get_serial_sequence(table_name: string, column_name: string) → string

Returns the name of the sequence used by the given column_name in the table table_name.

+		Stable
pg_get_viewdef(view_oid: oid) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_get_viewdef(view_oid: oid, pretty_bool: bool) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_has_role(role: string, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(role: oid, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(user: string, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: string, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_is_other_temp_schema(oid: oid) → bool

Returns true if the given OID is the OID of another session’s temporary schema. (This can be useful, for example, to exclude other sessions’ temporary tables from a catalog display.)

+		Stable
pg_my_temp_schema() → oid

Returns the OID of the current session’s temporary schema, or zero if it has none (because it has not created any temporary tables).

+		Stable
pg_relation_is_updatable(reloid: oid, include_triggers: bool) → int4

Returns the update events the relation supports.

+		Stable
pg_sequence_last_value(sequence_oid: oid) → int

Returns the last value generated by a sequence, or NULL if the sequence has not been used yet.

+		Volatile
pg_sleep(seconds: float) → bool

pg_sleep makes the current session’s process sleep until seconds seconds have elapsed. seconds is a value of type double precision, so fractional-second delays can be specified.

+		Volatile
pg_table_is_visible(oid: oid) → bool

Returns whether the table with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_type_is_visible(oid: oid) → bool

Returns whether the type with the given OID belongs to one of the schemas on the search path.

+		Stable
set_config(setting_name: string, new_value: string, is_local: bool) → string

System info

+		Volatile
shobj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a shared database object specified by its OID and the name of the containing system catalog. This is just like obj_description except that it is used for retrieving comments on shared objects (e.g. databases).

+		Stable
+ diff --git a/src/current/_includes/cockroach-generated/release-25.2/sql/operators.md b/src/current/_includes/cockroach-generated/release-25.2/sql/operators.md new file mode 100644 index 00000000000..0adf385f4c5 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.2/sql/operators.md @@ -0,0 +1,663 @@ + + + + + +
#Return
int # intint
varbit # varbitvarbit
+ + + + +
#>Return
jsonb #> string[]jsonb
+ + + + +
#>>Return
jsonb #>> string[]string
+ + + + + + + + + +
%Return
decimal % decimaldecimal
decimal % intdecimal
float % floatfloat
int % decimaldecimal
int % intint
string % stringbool
+ + + + + + +
&Return
inet & inetinet
int & intint
varbit & varbitvarbit
+ + + + + + + + + +
&&Return
anyelement && anyelementbool
box2d && box2dbool
box2d && geometrybool
geometry && box2dbool
geometry && geometrybool
inet && inetbool
+ + + + + + + + + + + + + + + +
*Return
decimal * decimaldecimal
decimal * intdecimal
decimal * intervalinterval
float * floatfloat
float * intervalinterval
int * decimaldecimal
int * intint
int * intervalinterval
interval * decimalinterval
interval * floatinterval
interval * intinterval
vector * vectorvector
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Return
+decimaldecimal
+floatfloat
+intint
+intervalinterval
date + intdate
date + intervaltimestamp
date + timetimestamp
date + timetztimestamptz
decimal + decimaldecimal
decimal + intdecimal
decimal + pg_lsnpg_lsn
float + floatfloat
inet + intinet
int + datedate
int + decimaldecimal
int + inetinet
int + intint
interval + datetimestamp
interval + intervalinterval
interval + timetime
interval + timestamptimestamp
interval + timestamptztimestamptz
interval + timetztimetz
pg_lsn + decimalpg_lsn
time + datetimestamp
time + intervaltime
timestamp + intervaltimestamp
timestamptz + intervaltimestamptz
timetz + datetimestamptz
timetz + intervaltimetz
vector + vectorvector
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
-Return
-decimaldecimal
-floatfloat
-intint
-intervalinterval
date - dateint
date - intdate
date - intervaltimestamp
date - timetimestamp
decimal - decimaldecimal
decimal - intdecimal
float - floatfloat
inet - inetint
inet - intinet
int - decimaldecimal
int - intint
interval - intervalinterval
jsonb - intjsonb
jsonb - stringjsonb
jsonb - string[]jsonb
pg_lsn - decimalpg_lsn
pg_lsn - pg_lsndecimal
time - intervaltime
time - timeinterval
timestamp - intervaltimestamp
timestamp - timestampinterval
timestamp - timestamptzinterval
timestamptz - intervaltimestamptz
timestamptz - timestampinterval
timestamptz - timestamptzinterval
timetz - intervaltimetz
vector - vectorvector
+ + + + + +
->Return
jsonb -> intjsonb
jsonb -> stringjsonb
+ + + + + +
->>Return
jsonb ->> intstring
jsonb ->> stringstring
+ + + + + + + + + + +
/Return
decimal / decimaldecimal
decimal / intdecimal
float / floatfloat
int / decimaldecimal
int / intdecimal
interval / floatinterval
interval / intinterval
+ + + + + + + + +
//Return
decimal // decimaldecimal
decimal // intdecimal
float // floatfloat
int // decimaldecimal
int // intint
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<Return
anyenum < anyenumbool
bool < boolbool
bool[] < bool[]bool
box2d < box2dbool
bpchar < bpcharbool
bytes < bytesbool
bytes[] < bytes[]bool
collatedstring < collatedstringbool
collatedstring{*} < collatedstring{*}bool
date < datebool
date < timestampbool
date < timestamptzbool
date[] < date[]bool
decimal < decimalbool
decimal < floatbool
decimal < intbool
decimal[] < decimal[]bool
float < decimalbool
float < floatbool
float < intbool
float[] < float[]bool
geography < geographybool
geometry < geometrybool
inet < inetbool
inet[] < inet[]bool
int < decimalbool
int < floatbool
int < intbool
int < oidbool
int[] < int[]bool
interval < intervalbool
interval[] < interval[]bool
jsonb < jsonbbool
oid < intbool
oid < oidbool
pg_lsn < pg_lsnbool
refcursor < refcursorbool
string < stringbool
string[] < string[]bool
time < timebool
time < timetzbool
time[] < time[]bool
timestamp < datebool
timestamp < timestampbool
timestamp < timestamptzbool
timestamp[] < timestamp[]bool
timestamptz < datebool
timestamptz < timestampbool
timestamptz < timestamptzbool
timestamptz < timestamptzbool
timetz < timebool
timetz < timetzbool
tuple < tuplebool
uuid < uuidbool
uuid[] < uuid[]bool
varbit < varbitbool
vector < vectorbool
+ + + + +
<#>Return
vector <#> vectorfloat
+ + + + +
<->Return
vector <-> vectorfloat
+ + + + + + +
<<Return
inet << inetbool
int << intint
varbit << intvarbit
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<=Return
anyenum <= anyenumbool
bool <= boolbool
bool[] <= bool[]bool
box2d <= box2dbool
bpchar <= bpcharbool
bytes <= bytesbool
bytes[] <= bytes[]bool
collatedstring <= collatedstringbool
collatedstring{*} <= collatedstring{*}bool
date <= datebool
date <= timestampbool
date <= timestamptzbool
date[] <= date[]bool
decimal <= decimalbool
decimal <= floatbool
decimal <= intbool
decimal[] <= decimal[]bool
float <= decimalbool
float <= floatbool
float <= intbool
float[] <= float[]bool
geography <= geographybool
geometry <= geometrybool
inet <= inetbool
inet[] <= inet[]bool
int <= decimalbool
int <= floatbool
int <= intbool
int <= oidbool
int[] <= int[]bool
interval <= intervalbool
interval[] <= interval[]bool
jsonb <= jsonbbool
oid <= intbool
oid <= oidbool
pg_lsn <= pg_lsnbool
refcursor <= refcursorbool
string <= stringbool
string[] <= string[]bool
time <= timebool
time <= timetzbool
time[] <= time[]bool
timestamp <= datebool
timestamp <= timestampbool
timestamp <= timestamptzbool
timestamp[] <= timestamp[]bool
timestamptz <= datebool
timestamptz <= timestampbool
timestamptz <= timestamptzbool
timestamptz <= timestamptzbool
timetz <= timebool
timetz <= timetzbool
tuple <= tuplebool
uuid <= uuidbool
uuid[] <= uuid[]bool
varbit <= varbitbool
vector <= vectorbool
+ + + + +
<=>Return
vector <=> vectorfloat
+ + + + + +
<@Return
anyelement <@ anyelementbool
jsonb <@ jsonbbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
=Return
anyenum = anyenumbool
bool = boolbool
bool[] = bool[]bool
box2d = box2dbool
bpchar = bpcharbool
bytes = bytesbool
bytes[] = bytes[]bool
collatedstring = collatedstringbool
collatedstring{*} = collatedstring{*}bool
date = datebool
date = timestampbool
date = timestamptzbool
date[] = date[]bool
decimal = decimalbool
decimal = floatbool
decimal = intbool
decimal[] = decimal[]bool
float = decimalbool
float = floatbool
float = intbool
float[] = float[]bool
geography = geographybool
geometry = geometrybool
inet = inetbool
inet[] = inet[]bool
int = decimalbool
int = floatbool
int = intbool
int = oidbool
int[] = int[]bool
interval = intervalbool
interval[] = interval[]bool
jsonb = jsonbbool
oid = intbool
oid = oidbool
pg_lsn = pg_lsnbool
refcursor = refcursorbool
string = stringbool
string[] = string[]bool
time = timebool
time = timetzbool
time[] = time[]bool
timestamp = datebool
timestamp = timestampbool
timestamp = timestamptzbool
timestamp[] = timestamp[]bool
timestamptz = datebool
timestamptz = timestampbool
timestamptz = timestamptzbool
timestamptz = timestamptzbool
timetz = timebool
timetz = timetzbool
tsquery = tsquerybool
tsvector = tsvectorbool
tuple = tuplebool
uuid = uuidbool
uuid[] = uuid[]bool
varbit = varbitbool
vector = vectorbool
+ + + + + + +
>>Return
inet >> inetbool
int >> intint
varbit >> intvarbit
+ + + + +
?Return
jsonb ? stringbool
+ + + + +
?&Return
jsonb ?& string[]bool
+ + + + +
?|Return
jsonb ?| string[]bool
+ + + + + +
@>Return
anyelement @> anyelementbool
jsonb @> jsonbbool
+ + + + + +
@@Return
tsquery @@ tsvectorbool
tsvector @@ tsquerybool
+ + + + +
ILIKEReturn
string ILIKE stringbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
INReturn
anyenum IN tuplebool
bool IN tuplebool
box2d IN tuplebool
bpchar IN tuplebool
bytes IN tuplebool
collatedstring IN tuplebool
date IN tuplebool
decimal IN tuplebool
float IN tuplebool
geography IN tuplebool
geometry IN tuplebool
inet IN tuplebool
int IN tuplebool
interval IN tuplebool
jsonb IN tuplebool
oid IN tuplebool
pg_lsn IN tuplebool
refcursor IN tuplebool
string IN tuplebool
time IN tuplebool
timestamp IN tuplebool
timestamptz IN tuplebool
timetz IN tuplebool
tuple IN tuplebool
uuid IN tuplebool
varbit IN tuplebool
vector IN tuplebool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IS NOT DISTINCT FROMReturn
anyelement IS NOT DISTINCT FROM unknownbool
anyenum IS NOT DISTINCT FROM anyenumbool
bool IS NOT DISTINCT FROM boolbool
bool[] IS NOT DISTINCT FROM bool[]bool
box2d IS NOT DISTINCT FROM box2dbool
bpchar IS NOT DISTINCT FROM bpcharbool
bytes IS NOT DISTINCT FROM bytesbool
bytes[] IS NOT DISTINCT FROM bytes[]bool
collatedstring IS NOT DISTINCT FROM collatedstringbool
collatedstring{*} IS NOT DISTINCT FROM collatedstring{*}bool
date IS NOT DISTINCT FROM datebool
date IS NOT DISTINCT FROM timestampbool
date IS NOT DISTINCT FROM timestamptzbool
date[] IS NOT DISTINCT FROM date[]bool
decimal IS NOT DISTINCT FROM decimalbool
decimal IS NOT DISTINCT FROM floatbool
decimal IS NOT DISTINCT FROM intbool
decimal[] IS NOT DISTINCT FROM decimal[]bool
float IS NOT DISTINCT FROM decimalbool
float IS NOT DISTINCT FROM floatbool
float IS NOT DISTINCT FROM intbool
float[] IS NOT DISTINCT FROM float[]bool
geography IS NOT DISTINCT FROM geographybool
geometry IS NOT DISTINCT FROM geometrybool
inet IS NOT DISTINCT FROM inetbool
inet[] IS NOT DISTINCT FROM inet[]bool
int IS NOT DISTINCT FROM decimalbool
int IS NOT DISTINCT FROM floatbool
int IS NOT DISTINCT FROM intbool
int IS NOT DISTINCT FROM oidbool
int[] IS NOT DISTINCT FROM int[]bool
interval IS NOT DISTINCT FROM intervalbool
interval[] IS NOT DISTINCT FROM interval[]bool
jsonb IS NOT DISTINCT FROM jsonbbool
jsonpath IS NOT DISTINCT FROM jsonpathbool
oid IS NOT DISTINCT FROM intbool
oid IS NOT DISTINCT FROM oidbool
pg_lsn IS NOT DISTINCT FROM pg_lsnbool
refcursor IS NOT DISTINCT FROM refcursorbool
string IS NOT DISTINCT FROM stringbool
string[] IS NOT DISTINCT FROM string[]bool
time IS NOT DISTINCT FROM timebool
time IS NOT DISTINCT FROM timetzbool
time[] IS NOT DISTINCT FROM time[]bool
timestamp IS NOT DISTINCT FROM datebool
timestamp IS NOT DISTINCT FROM timestampbool
timestamp IS NOT DISTINCT FROM timestamptzbool
timestamp[] IS NOT DISTINCT FROM timestamp[]bool
timestamptz IS NOT DISTINCT FROM datebool
timestamptz IS NOT DISTINCT FROM timestampbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timetz IS NOT DISTINCT FROM timebool
timetz IS NOT DISTINCT FROM timetzbool
tsquery IS NOT DISTINCT FROM tsquerybool
tsvector IS NOT DISTINCT FROM tsvectorbool
tuple IS NOT DISTINCT FROM tuplebool
unknown IS NOT DISTINCT FROM unknownbool
unknown IS NOT DISTINCT FROM voidbool
uuid IS NOT DISTINCT FROM uuidbool
uuid[] IS NOT DISTINCT FROM uuid[]bool
varbit IS NOT DISTINCT FROM varbitbool
vector IS NOT DISTINCT FROM vectorbool
void IS NOT DISTINCT FROM unknownbool
+ + + + +
LIKEReturn
string LIKE stringbool
+ + + + +
SIMILAR TOReturn
string SIMILAR TO stringbool
+ + + + + + + + +
^Return
decimal ^ decimaldecimal
decimal ^ intdecimal
float ^ floatfloat
int ^ decimaldecimal
int ^ intint
+ + + + + + +
|Return
inet | inetinet
int | intint
varbit | varbitvarbit
+ + + + + +
|/Return
|/decimaldecimal
|/floatfloat
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
||Return
bool || bool[]bool[]
bool || stringstring
bool[] || boolbool[]
bool[] || bool[]bool[]
box2d || box2dbox2d
box2d || stringstring
bytes || bytesbytes
bytes || bytes[]bytes[]
bytes[] || bytesbytes[]
bytes[] || bytes[]bytes[]
date || date[]date[]
date || stringstring
date[] || datedate[]
date[] || date[]date[]
decimal || decimal[]decimal[]
decimal || stringstring
decimal[] || decimaldecimal[]
decimal[] || decimal[]decimal[]
float || float[]float[]
float || stringstring
float[] || floatfloat[]
float[] || float[]float[]
geography || geographygeography
geography || stringstring
geometry || geometrygeometry
geometry || stringstring
inet || inet[]inet[]
inet || stringstring
inet[] || inetinet[]
inet[] || inet[]inet[]
int || int[]int[]
int || stringstring
int[] || intint[]
int[] || int[]int[]
interval || interval[]interval[]
interval || stringstring
interval[] || intervalinterval[]
interval[] || interval[]interval[]
jsonb || jsonbjsonb
jsonb || stringstring
oid || oidoid
oid || stringstring
pg_lsn || pg_lsnpg_lsn
pg_lsn || stringstring
refcursor || refcursorrefcursor
refcursor || stringstring
string || boolstring
string || box2dstring
string || datestring
string || decimalstring
string || floatstring
string || geographystring
string || geometrystring
string || inetstring
string || intstring
string || intervalstring
string || jsonbstring
string || oidstring
string || pg_lsnstring
string || refcursorstring
string || stringstring
string || string[]string[]
string || timestring
string || timestampstring
string || timestamptzstring
string || timetzstring
string || tuplestring
string || uuidstring
string || varbitstring
string[] || stringstring[]
string[] || string[]string[]
time || stringstring
time || time[]time[]
time[] || timetime[]
time[] || time[]time[]
timestamp || stringstring
timestamp || timestamp[]timestamp[]
timestamp[] || timestamptimestamp[]
timestamp[] || timestamp[]timestamp[]
timestamptz || stringstring
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timetz || stringstring
timetz || timetztimetz
tuple || stringstring
uuid || stringstring
uuid || uuid[]uuid[]
uuid[] || uuiduuid[]
uuid[] || uuid[]uuid[]
varbit || stringstring
varbit || varbitvarbit
+ + + + + +
||/Return
||/decimaldecimal
||/floatfloat
+ + + + + + + + + + + +
~Return
~inetinet
~intint
~varbitvarbit
box2d ~ box2dbool
box2d ~ geometrybool
geometry ~ box2dbool
geometry ~ geometrybool
string ~ stringbool
+ + + + +
~*Return
string ~* stringbool
diff --git a/src/current/_includes/cockroach-generated/release-25.2/sql/window_functions.md b/src/current/_includes/cockroach-generated/release-25.2/sql/window_functions.md new file mode 100644 index 00000000000..e1032ff82de --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.2/sql/window_functions.md @@ -0,0 +1,413 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cume_dist() → float

Calculates the relative rank of the current row: (number of rows preceding or peer with current row) / (total rows).

+		Immutable
dense_rank() → int

Calculates the rank of the current row without gaps; this function counts peer groups.

+		Immutable
first_value(val: bool) → bool

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: bytes) → bytes

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: date) → date

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: decimal) → decimal

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: float) → float

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: inet) → inet

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: int) → int

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: interval) → interval

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: string) → string

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: time) → time

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: uuid) → uuid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: box2d) → box2d

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geography) → geography

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geometry) → geometry

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: oid) → oid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timetz) → timetz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: varbit) → varbit

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
lag(val: bool) → bool

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: bytes) → bytes

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: date) → date

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: date, n: int) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: decimal) → decimal

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: float) → float

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: float, n: int) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: inet) → inet

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: int) → int

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: int, n: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: interval) → interval

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: string) → string

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: string, n: int) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: time) → time

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: time, n: int) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamp) → timestamp

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz) → timestamptz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: uuid) → uuid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: box2d) → box2d

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geography) → geography

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geometry) → geometry

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: jsonb) → jsonb

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: oid) → oid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn) → pg_lsn

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: refcursor) → refcursor

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timetz) → timetz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: varbit) → varbit

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
last_value(val: bool) → bool

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: bytes) → bytes

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: date) → date

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: decimal) → decimal

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: float) → float

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: inet) → inet

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: int) → int

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: interval) → interval

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: string) → string

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: time) → time

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: uuid) → uuid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: box2d) → box2d

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geography) → geography

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geometry) → geometry

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: oid) → oid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timetz) → timetz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: varbit) → varbit

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
lead(val: bool) → bool

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: bytes) → bytes

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: date) → date

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: date, n: int) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: decimal) → decimal

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: float) → float

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: float, n: int) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: inet) → inet

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: int) → int

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: int, n: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: interval) → interval

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: string) → string

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: string, n: int) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: time) → time

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: time, n: int) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamp) → timestamp

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz) → timestamptz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: uuid) → uuid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: box2d) → box2d

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geography) → geography

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geometry) → geometry

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: jsonb) → jsonb

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: oid) → oid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn) → pg_lsn

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: refcursor) → refcursor

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timetz) → timetz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: varbit) → varbit

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
nth_value(val: bool, n: int) → bool

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: bytes, n: int) → bytes

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: date, n: int) → date

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: decimal, n: int) → decimal

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: float, n: int) → float

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: inet, n: int) → inet

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: int, n: int) → int

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: interval, n: int) → interval

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: string, n: int) → string

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: time, n: int) → time

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: uuid, n: int) → uuid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: box2d, n: int) → box2d

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geography, n: int) → geography

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geometry, n: int) → geometry

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: oid, n: int) → oid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timetz, n: int) → timetz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: varbit, n: int) → varbit

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
ntile(n: int) → int

Calculates an integer ranging from 1 to n, dividing the partition as equally as possible.

+		Immutable
percent_rank() → float

Calculates the relative rank of the current row: (rank - 1) / (total rows - 1).

+		Immutable
rank() → int

Calculates the rank of the current row with gaps; same as row_number of its first peer.

+		Immutable
row_number() → int

Calculates the number of the current row within its partition, counting from 1.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-25.3/eventlog.md b/src/current/_includes/cockroach-generated/release-25.3/eventlog.md new file mode 100644 index 00000000000..a165d7db3eb --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.3/eventlog.md @@ -0,0 +1,3549 @@ +Certain notable events are reported using a structured format. +Commonly, these notable events are also copied to the table +`system.eventlog`, unless the cluster setting +`server.eventlog.enabled` is unset. + +Additionally, notable events are copied to specific external logging +channels in log messages, where they can be collected for further processing. + +The sections below document the possible notable event types +in this version of CockroachDB. For each event type, a table +documents the possible fields. A field may be omitted from +an event if its value is empty or zero. + +A field is also considered "Sensitive" if it may contain +application-specific information or personally identifiable information (PII). In that case, +the copy of the event sent to the external logging channel +will contain redaction markers in a format that is compatible +with the redaction facilities in [`cockroach debug zip`](cockroach-debug-zip.html) +and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html), +provided the `redactable` functionality is enabled on the logging sink. + +Events not documented on this page will have an unstructured format in log messages. + +## Changefeed telemetry events + +Events in this category pertain to changefeed usage and metrics. + +Events in this category are logged to the `TELEMETRY` channel. + + +### `alter_changefeed` + +An event of type `alter_changefeed` is an event for any ALTER CHANGEFEED statements that are run. + + +| Field | Description | Sensitive | +|--|--|--| +| `PreviousDescription` | The description of the changefeed job before the ALTER CHANGEFEED. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `changefeed_canceled` + +An event of type `changefeed_canceled` is an event for any changefeed cancellations. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `changefeed_emitted_bytes` + +An event of type `changefeed_emitted_bytes` is an event representing the bytes emitted by a changefeed over an interval. + + +| Field | Description | Sensitive | +|--|--|--| +| `EmittedBytes` | The number of bytes emitted. | no | +| `EmittedMessages` | The number of messages emitted. | no | +| `LoggingInterval` | The time period in nanoseconds between emitting telemetry events of this type (per-aggregator). | no | +| `Closing` | Flag to indicate that the changefeed is closing. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `changefeed_failed` + +An event of type `changefeed_failed` is an event for any changefeed failure since the plan hook +was triggered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FailureType` | The reason / environment with which the changefeed failed (ex: connection_closed, changefeed_behind). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `create_changefeed` + +An event of type `create_changefeed` is an event for any CREATE CHANGEFEED query that +successfully starts running. Failed CREATE statements will show up as +ChangefeedFailed events. + + +| Field | Description | Sensitive | +|--|--|--| +| `Transformation` | Flag representing whether the changefeed is using CDC queries. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +## Cluster-level events + +Events in this category pertain to an entire cluster and are +not relative to any particular tenant. + +In a multi-tenant setup, the `system.eventlog` table for individual +tenants cannot contain a copy of cluster-level events; conversely, +the `system.eventlog` table in the system tenant cannot contain the +SQL-level events for individual tenants. + +Events in this category are logged to the `OPS` channel. + + +### `certs_reload` + +An event of type `certs_reload` is recorded when the TLS certificates are +reloaded/rotated from disk. + + +| Field | Description | Sensitive | +|--|--|--| +| `Success` | Whether the operation completed without errors. | no | +| `ErrorMessage` | If an error was encountered, the text of the error. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `disk_slowness_cleared` + +An event of type `disk_slowness_cleared` is recorded when disk slowness in a store has cleared. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `disk_slowness_detected` + +An event of type `disk_slowness_detected` is recorded when a store observes disk slowness +events. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `low_disk_space` + +An event of type `low_disk_space` is emitted when a store is reaching capacity, as we reach +certain thresholds. It is emitted periodically while we are in a low disk +state. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | +| `PercentThreshold` | The free space percent threshold that we went under. | no | +| `AvailableBytes` | | no | +| `TotalBytes` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `node_decommissioned` + +An event of type `node_decommissioned` is recorded when a node is marked as +decommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_decommissioning` + +An event of type `node_decommissioning` is recorded when a node is marked as +decommissioning. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_join` + +An event of type `node_join` is recorded when a node joins the cluster. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_recommissioned` + +An event of type `node_recommissioned` is recorded when a decommissioning node is +recommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_restart` + +An event of type `node_restart` is recorded when an existing node rejoins the cluster +after being offline. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_connection_timeout` + +An event of type `node_shutdown_connection_timeout` is recorded when SQL connections remain open +during shutdown, after waiting for the server.shutdown.connections.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still open after waiting for the client to close them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.connections.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_transaction_timeout` + +An event of type `node_shutdown_transaction_timeout` is recorded when SQL transactions remain open +during shutdown, after waiting for the server.shutdown.transactions.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still running SQL transactions after waiting for the client to end them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.transactions.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `tenant_shared_service_start` + +An event of type `tenant_shared_service_start` is recorded when a tenant server +is started inside the same process as the KV layer. + + +| Field | Description | Sensitive | +|--|--|--| +| `OK` | Whether the startup was successful. | no | +| `ErrorText` | If the startup failed, the text of the error. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +### `tenant_shared_service_stop` + +An event of type `tenant_shared_service_stop` is recorded when a tenant server +is shut down inside the same process as the KV layer. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +## Debugging events + +Events in this category pertain to debugging operations performed by +operators or (more commonly) Cockroach Labs employees. These operations can +e.g. directly access and mutate internal state, breaking system invariants. + +Events in this category are logged to the `OPS` channel. + + +### `debug_recover_replica` + +An event of type `debug_recover_replica` is recorded when unsafe loss of quorum recovery is performed. + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `StoreID` | | no | +| `SurvivorReplicaID` | | no | +| `UpdatedReplicaID` | | no | +| `StartKey` | | yes | +| `EndKey` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +### `debug_send_kv_batch` + +An event of type `debug_send_kv_batch` is recorded when an arbitrary KV BatchRequest is submitted +to the cluster via the `debug send-kv-batch` CLI command. + + +| Field | Description | Sensitive | +|--|--|--| +| `BatchRequest` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +## Health events + +Events in this category pertain to the health of one or more servers. + +Events in this category are logged to the `HEALTH` channel. + + +### `hot_ranges_stats` + +An event of type `hot_ranges_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `Qps` | | no | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | yes | +| `LeaseholderNodeID` | LeaseholderNodeID indicates the Node ID that is the current leaseholder for the given range. | no | +| `WritesPerSecond` | Writes per second is the recent number of keys written per second on this range. | no | +| `ReadsPerSecond` | Reads per second is the recent number of keys read per second on this range. | no | +| `WriteBytesPerSecond` | Write bytes per second is the recent number of bytes written per second on this range. | no | +| `ReadBytesPerSecond` | Read bytes per second is the recent number of bytes read per second on this range. | no | +| `CPUTimePerSecond` | CPU time per second is the recent cpu usage in nanoseconds of this range. | no | +| `Databases` | Databases for the range. | no | +| `Tables` | Tables for the range | no | +| `Indexes` | Indexes for the range | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `runtime_stats` + +An event of type `runtime_stats` is recorded every 10 seconds as server health metrics. + + +| Field | Description | Sensitive | +|--|--|--| +| `MemRSSBytes` | The process resident set size. Expressed as bytes. | no | +| `GoroutineCount` | The number of goroutines. | no | +| `MemStackSysBytes` | The stack system memory used. Expressed as bytes. | no | +| `GoAllocBytes` | The memory allocated by Go. Expressed as bytes. | no | +| `GoTotalBytes` | The total memory allocated by Go but not released. Expressed as bytes. | no | +| `GoStatsStaleness` | The staleness of the Go memory statistics. Expressed in seconds. | no | +| `HeapFragmentBytes` | The amount of heap fragmentation. Expressed as bytes. | no | +| `HeapReservedBytes` | The amount of heap reserved. Expressed as bytes. | no | +| `HeapReleasedBytes` | The amount of heap released. Expressed as bytes. | no | +| `CGoAllocBytes` | The memory allocated outside of Go. Expressed as bytes. | no | +| `CGoTotalBytes` | The total memory allocated outside of Go but not released. Expressed as bytes. | no | +| `CGoCallRate` | The total number of calls outside of Go over time. Expressed as operations per second. | no | +| `CPUUserPercent` | The user CPU percentage. | no | +| `CPUSysPercent` | The system CPU percentage. | no | +| `GCPausePercent` | The GC pause percentage. | no | +| `GCRunCount` | The total number of GC runs. | no | +| `NetHostRecvBytes` | The bytes received on all network interfaces since this process started. | no | +| `NetHostSendBytes` | The bytes sent on all network interfaces since this process started. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Job events + +Events in this category pertain to long-running jobs that are orchestrated by +a node's job registry. These system processes can create and/or modify stored +objects during the course of their execution. + +A job might choose to emit multiple events during its execution when +transitioning from one "state" to another. +Egs: IMPORT/RESTORE will emit events on job creation and successful +completion. If the job fails, events will be emitted on job creation, +failure, and successful revert. + +Events in this category are logged to the `OPS` channel. + + +### `import` + +An event of type `import` is recorded when an import job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `restore` + +An event of type `restore` is recorded when a restore job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `status_change` + +An event of type `status_change` is recorded when a job changes statuses. + + +| Field | Description | Sensitive | +|--|--|--| +| `JobID` | The ID of the job that is changing statuses. | no | +| `JobType` | The type of the job that is changing statuses. | no | +| `Description` | A human parsable description of the status change | partially | +| `PreviousStatus` | The status that the job is transitioning out of | no | +| `NewStatus` | The status that the job has transitioned into | no | +| `RunNum` | The run number of the job. | no | +| `Error` | An error that may have occurred while the job was running. | yes | +| `FinalResumeErr` | An error that occurred that requires the job to be reverted. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Miscellaneous SQL events + +Events in this category report miscellaneous SQL events. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own system.eventlog table. + +Events in this category are logged to the `OPS` channel. + + +### `set_cluster_setting` + +An event of type `set_cluster_setting` is recorded when a cluster setting is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `set_tenant_cluster_setting` + +An event of type `set_tenant_cluster_setting` is recorded when a cluster setting override +is changed, either for another tenant or for all tenants. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | +| `TenantId` | The target Tenant ID. Empty if targeting all tenants. | no | +| `AllTenants` | Whether the override applies to all tenants. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +## SQL Access Audit Events + +Events in this category are generated when a table has been +marked as audited via `ALTER TABLE ... EXPERIMENTAL_AUDIT SET`. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SENSITIVE_ACCESS` channel. + + +### `admin_query` + +An event of type `admin_query` is recorded when a user with admin privileges (the user +is directly or indirectly a member of the admin role) executes a query. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `role_based_audit_event` + +An event of type `role_based_audit_event` is an audit event recorded when an executed query belongs to a user whose role +membership(s) correspond to any role that is enabled to emit an audit log via the sql.log.user_audit +cluster setting. + + +| Field | Description | Sensitive | +|--|--|--| +| `Role` | The configured audit role that emitted this log. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sensitive_table_access` + +An event of type `sensitive_table_access` is recorded when an access is performed to +a table marked as audited. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table being audited. | yes | +| `AccessMode` | How the table was accessed (r=read / rw=read/write). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +## SQL Execution Log + +Events in this category report executed queries. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `query_execute` + +An event of type `query_execute` is recorded when a query is executed, +and the cluster setting `sql.log.all_statements.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +## SQL Logical Schema Changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the SQL logical +schema. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SQL_SCHEMA` channel. + + +### `alter_database_add_region` + +An event of type `alter_database_add_region` is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `RegionName` | The region being added. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_drop_region` + +AlterDatabaseAddRegion is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `RegionName` | The region being dropped. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_placement` + +An event of type `alter_database_placement` is recorded when the database placement is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `Placement` | The new placement policy. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_primary_region` + +An event of type `alter_database_primary_region` is recorded when a primary region is added/modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `PrimaryRegionName` | The new primary region. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_database_set_zone_config_extension` + +An event of type `alter_database_set_zone_config_extension` is recorded when a zone config extension is changed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `alter_database_survival_goal` + +An event of type `alter_database_survival_goal` is recorded when the survival goal is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `SurvivalGoal` | The new survival goal | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_function_options` + +An event of type `alter_function_options` is recorded when a user-defined function's options are +altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the affected function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_index` + +An event of type `alter_index` is recorded when an index is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_index_visible` + +AlterIndex is recorded when an index visibility is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `NotVisible` | Set true if index is not visible. NOTE: THIS FIELD IS DEPRECATED in favor of invisibility. | no | +| `Invisibility` | The new invisibility of the affected index. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_sequence` + +An event of type `alter_sequence` is recorded when a sequence is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_table` + +An event of type `alter_table` is recorded when a table is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update, if any. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_type` + +EventAlterType is recorded when a user-defined type is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_column` + +An event of type `comment_on_column` is recorded when a column is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected column. | no | +| `ColumnName` | The affected column. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_constraint` + +An event of type `comment_on_constraint` is recorded when an constraint is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected constraint. | no | +| `ConstraintName` | The name of the affected constraint. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_database` + +CommentOnTable is recorded when a database is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_index` + +An event of type `comment_on_index` is recorded when an index is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_schema` + + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | Name of the affected schema. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_table` + +An event of type `comment_on_table` is recorded when a table is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `comment_on_type` + +An event of type `comment_on_type` is recorded when a type is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_database` + +An event of type `create_database` is recorded when a database is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the new database. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_function` + +An event of type `create_function` is recorded when a user-defined function is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the created function. | no | +| `IsReplace` | If the new function is a replace of an existing function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_index` + +An event of type `create_index` is recorded when an index is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the new index. | no | +| `IndexName` | The name of the new index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_policy` + +An event of type `create_policy` is recorded when a policy is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the policy's table. | no | +| `PolicyName` | Name of the created policy. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_schema` + +An event of type `create_schema` is recorded when a schema is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the new schema. | no | +| `Owner` | The name of the owner for the new schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_sequence` + +An event of type `create_sequence` is recorded when a sequence is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the new sequence. | no | +| `Owner` | The name of the owner for the new sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_statistics` + +An event of type `create_statistics` is recorded when statistics are collected for a +table. + +Events of this type are only collected when the cluster setting +`sql.stats.post_events.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table for which the statistics were created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_table` + +An event of type `create_table` is recorded when a table is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the new table. | no | +| `Owner` | The name of the owner for the new table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_trigger` + +An event of type `create_trigger` is recorded when a trigger is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the trigger's table. | no | +| `TriggerName` | Name of the created trigger. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_type` + +An event of type `create_type` is recorded when a user-defined type is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the new type. | no | +| `Owner` | The name of the owner for the new type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_view` + +An event of type `create_view` is recorded when a view is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the new view. | no | +| `Owner` | The name of the owner of the new view. | no | +| `ViewQuery` | The SQL selection clause used to define the view. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_database` + +An event of type `drop_database` is recorded when a database is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | no | +| `DroppedSchemaObjects` | The names of the schemas dropped by a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_function` + +An event of type `drop_function` is recorded when a user-defined function is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the dropped function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_index` + +An event of type `drop_index` is recorded when an index is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_policy` + +An event of type `drop_policy` is recorded when a policy is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the policy's table. | no | +| `PolicyName` | Name of the dropped policy. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_schema` + +An event of type `drop_schema` is recorded when a schema is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_sequence` + +An event of type `drop_sequence` is recorded when a sequence is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_table` + +An event of type `drop_table` is recorded when a table is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_trigger` + +An event of type `drop_trigger` is recorded when a trigger is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the trigger's table. | no | +| `TriggerName` | Name of the dropped trigger. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_type` + +An event of type `drop_type` is recorded when a user-defined type is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_view` + +An event of type `drop_view` is recorded when a view is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the affected view. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `finish_schema_change` + +An event of type `finish_schema_change` is recorded when a previously initiated schema +change has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to complete. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `finish_schema_change_rollback` + +An event of type `finish_schema_change_rollback` is recorded when a previously +initiated schema change rollback has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to rollback. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `force_delete_table_data_entry` + + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_database` + +An event of type `rename_database` is recorded when a database is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The old name of the affected database. | no | +| `NewDatabaseName` | The new name of the affected database. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_function` + +An event of type `rename_function` is recorded when a user-defined function is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The old name of the affected function. | no | +| `NewFunctionName` | The new name of the affected function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_schema` + +An event of type `rename_schema` is recorded when a schema is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The old name of the affected schema. | no | +| `NewSchemaName` | The new name of the affected schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_table` + +An event of type `rename_table` is recorded when a table, sequence or view is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The old name of the affected table. | no | +| `NewTableName` | The new name of the affected table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `rename_type` + +An event of type `rename_type` is recorded when a user-defined type is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The old name of the affected type. | no | +| `NewTypeName` | The new name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `reverse_schema_change` + +An event of type `reverse_schema_change` is recorded when an in-progress schema change +encounters a problem and is reversed. + + +| Field | Description | Sensitive | +|--|--|--| +| `Error` | The error encountered that caused the schema change to be reversed. The specific format of the error is variable and can change across releases without warning. | partially | +| `SQLSTATE` | The SQLSTATE code for the error. | no | +| `LatencyNanos` | The amount of time the schema change job took before being reverted. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `set_schema` + +An event of type `set_schema` is recorded when a table, view, sequence or type's schema is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorName` | The old name of the affected descriptor. | no | +| `NewDescriptorName` | The new name of the affected descriptor. | no | +| `DescriptorType` | The descriptor type being changed (table, view, sequence, type). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `truncate_table` + +An event of type `truncate_table` is recorded when a table is truncated. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_delete_descriptor` + +An event of type `unsafe_delete_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_delete_descriptor(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_delete_namespace_entry` + +An event of type `unsafe_delete_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_delete_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_upsert_descriptor` + +An event of type `unsafe_upsert_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_upsert_descriptor(). + + +| Field | Description | Sensitive | +|--|--|--| +| `PreviousDescriptor` | | yes | +| `NewDescriptor` | | yes | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `unsafe_upsert_namespace_entry` + +An event of type `unsafe_upsert_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_upsert_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `PreviousID` | | no | +| `Force` | | no | +| `FailedValidation` | | no | +| `ValidationErrors` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +## SQL Privilege changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the privilege +grants for stored objects. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `PRIVILEGES` channel. + + +### `alter_database_owner` + +An event of type `alter_database_owner` is recorded when a database's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database being affected. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_default_privileges` + +An event of type `alter_default_privileges` is recorded when default privileges are changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | +| `RoleName` | Either role_name should be populated or for_all_roles should be true. The role having its default privileges altered. | yes | +| `ForAllRoles` | Identifies if FOR ALL ROLES is used. | no | +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `alter_function_owner` + +AlterTableOwner is recorded when the owner of a user-defined function is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The name of the affected user-defined function. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_schema_owner` + +An event of type `alter_schema_owner` is recorded when a schema's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_table_owner` + +An event of type `alter_table_owner` is recorded when the owner of a table, view or sequence is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected object. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `alter_type_owner` + +An event of type `alter_type_owner` is recorded when the owner of a user-defiend type is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `change_database_privilege` + +An event of type `change_database_privilege` is recorded when privileges are +added to / removed from a user for a database object. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_function_privilege` + + + +| Field | Description | Sensitive | +|--|--|--| +| `FuncName` | The name of the affected function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_schema_privilege` + +An event of type `change_schema_privilege` is recorded when privileges are added to / +removed from a user for a schema object. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_table_privilege` + +An event of type `change_table_privilege` is recorded when privileges are added to / removed +from a user for a table, sequence or view object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_type_privilege` + +An event of type `change_type_privilege` is recorded when privileges are added to / +removed from a user for a type object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +## SQL Session events + +Events in this category report SQL client connections +and sessions. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SESSIONS` channel. + + +### `client_authentication_failed` + +An event of type `client_authentication_failed` is reported when a client session +did not authenticate successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Reason` | The reason for the authentication failure. See below for possible values for type `AuthFailReason`. | no | +| `Detail` | The detailed error for the authentication failure. | partially | +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_info` + +An event of type `client_authentication_info` is reported for intermediate +steps during the authentication process. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used, once known. | no | +| `Info` | The authentication progress message. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_ok` + +An event of type `client_authentication_ok` is reported when a client session +was authenticated successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_connection_end` + +An event of type `client_connection_end` is reported when a client connection +is closed. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_connection_start` + +An event of type `client_connection_start` is reported when a client connection +is established. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_session_end` + +An event of type `client_session_end` is reported when a client session +is completed. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +## SQL Slow Query Log + +Events in this category report slow query execution. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_PERF` channel. + + +### `large_row` + +An event of type `large_row` is recorded when a statement tries to write a row larger than +cluster setting `sql.guardrails.max_row_size_log` to the database. Multiple +LargeRow events will be recorded for statements writing multiple large rows. +LargeRow events are recorded before the transaction commits, so in the case +of transaction abort there will not be a corresponding row in the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query` + +An event of type `slow_query` is recorded when a query triggers the "slow query" condition. + +As of this writing, the condition requires: +- the cluster setting `sql.log.slow_query.latency_threshold` +set to a non-zero value, AND +- EITHER of the following conditions: +- the actual age of the query exceeds the configured threshold; AND/OR +- the query performs a full table/index scan AND the cluster setting +`sql.log.slow_query.experimental_full_table_scans.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit` + +An event of type `txn_rows_read_limit` is recorded when a transaction tries to read more rows than +cluster setting `sql.defaults.transaction_rows_read_log`. There will only be +a single record for a single transaction (unless it is retried) even if there +are more statement within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit` + +An event of type `txn_rows_written_limit` is recorded when a transaction tries to write more rows +than cluster setting `sql.defaults.transaction_rows_written_log`. There will +only be a single record for a single transaction (unless it is retried) even +if there are more mutation statements within the transaction that haven't +been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL Slow Query Log (Internal) + +Events in this category report slow query execution by +internal executors, i.e., when CockroachDB internally issues +SQL statements. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_INTERNAL_PERF` channel. + + +### `large_row_internal` + +An event of type `large_row_internal` is recorded when an internal query tries to write a row +larger than cluster settings `sql.guardrails.max_row_size_log` or +`sql.guardrails.max_row_size_err` to the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query_internal` + +An event of type `slow_query_internal` is recorded when a query triggers the "slow query" condition, +and the cluster setting `sql.log.slow_query.internal_queries.enabled` is +set. +See the documentation for the event type `slow_query` for details about +the "slow query" condition. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit_internal` + +An event of type `txn_rows_read_limit_internal` is recorded when an internal transaction tries to +read more rows than cluster setting `sql.defaults.transaction_rows_read_log` +or `sql.defaults.transaction_rows_read_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit_internal` + +An event of type `txn_rows_written_limit_internal` is recorded when an internal transaction tries to +write more rows than cluster setting +`sql.defaults.transaction_rows_written_log` or +`sql.defaults.transaction_rows_written_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL User and Role operations + +Events in this category pertain to SQL statements that modify the +properties of users and roles. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `USER_ADMIN` channel. + + +### `alter_role` + +An event of type `alter_role` is recorded when a role is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | +| `Options` | The options set on the user/role. | no | +| `SetInfo` | Information corresponding to an ALTER ROLE SET statement. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `create_role` + +An event of type `create_role` is recorded when a role is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the new user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `drop_role` + +An event of type `drop_role` is recorded when a role is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `grant_role` + +An event of type `grant_role` is recorded when a role is granted. + + +| Field | Description | Sensitive | +|--|--|--| +| `GranteeRoles` | The roles being granted to. | yes | +| `Members` | The roles being granted. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | + +### `password_hash_converted` + +An event of type `password_hash_converted` is recorded when the password credentials +are automatically converted server-side. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the user/role whose credentials have been converted. | yes | +| `OldMethod` | The previous hash method. | no | +| `NewMethod` | The new hash method. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Storage telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `level_stats` + +An event of type `level_stats` contains per-level statistics for an LSM. + + +| Field | Description | Sensitive | +|--|--|--| +| `Level` | level is the level ID in a LSM (e.g. level(L0) == 0, etc.) | no | +| `NumFiles` | num_files is the number of files in the level (gauge). | no | +| `SizeBytes` | size_bytes is the size of the level, in bytes (gauge). | no | +| `Score` | score is the compaction score of the level (gauge). | no | +| `BytesIn` | bytes_in is the number of bytes written to this level (counter). | no | +| `BytesIngested` | bytes_ingested is the number of bytes ingested into this level (counter). | no | +| `BytesMoved` | bytes_moved is the number of bytes moved into this level via a move-compaction (counter). | no | +| `BytesRead` | bytes_read is the number of bytes read from this level, during compactions (counter). | no | +| `BytesCompacted` | bytes_compacted is the number of bytes written to this level during compactions (counter). | no | +| `BytesFlushed` | bytes flushed is the number of bytes flushed to this level. This value is always zero for levels other than L0 (counter). | no | +| `TablesCompacted` | tables_compacted is the count of tables compacted into this level (counter). | no | +| `TablesFlushed` | tables_flushed is the count of tables flushed into this level (counter). | no | +| `TablesIngested` | tables_ingested is the count of tables ingested into this level (counter). | no | +| `TablesMoved` | tables_moved is the count of tables moved into this level via move-compactions (counter). | no | +| `NumSublevels` | num_sublevel is the count of sublevels for the level. This value is always zero for levels other than L0 (gauge). | no | + + + +### `store_stats` + +An event of type `store_stats` contains per store stats. + +Note that because stats are scoped to the lifetime of the process, counters +(and certain gauges) will be reset across node restarts. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeId` | node_id is the ID of the node. | no | +| `StoreId` | store_id is the ID of the store. | no | +| `Levels` | levels is a nested message containing per-level statistics. | yes | +| `CacheSize` | cache_size is the size of the cache for the store, in bytes (gauge). | no | +| `CacheCount` | cache_count is the number of items in the cache (gauge). | no | +| `CacheHits` | cache_hits is the number of cache hits (counter). | no | +| `CacheMisses` | cache_misses is the number of cache misses (counter). | no | +| `CompactionCountDefault` | compaction_count_default is the count of default compactions (counter). | no | +| `CompactionCountDeleteOnly` | compaction_count_delete_only is the count of delete-only compactions (counter). | no | +| `CompactionCountElisionOnly` | compaction_count_elision_only is the count of elision-only compactions (counter). | no | +| `CompactionCountMove` | compaction_count_move is the count of move-compactions (counter). | no | +| `CompactionCountRead` | compaction_count_read is the count of read-compactions (counter). | no | +| `CompactionCountRewrite` | compaction_count_rewrite is the count of rewrite-compactions (counter). | no | +| `CompactionNumInProgress` | compactions_num_in_progress is the number of compactions in progress (gauge). | no | +| `CompactionMarkedFiles` | compaction_marked_files is the count of files marked for compaction (gauge). | no | +| `FlushCount` | flush_count is the number of flushes (counter). | no | +| `FlushIngestCount` | | no | +| `FlushIngestTableCount` | | no | +| `FlushIngestTableBytes` | | no | +| `IngestCount` | ingest_count is the number of successful ingest operations (counter). | no | +| `MemtableSize` | memtable_size is the total size allocated to all memtables and (large) batches, in bytes (gauge). | no | +| `MemtableCount` | memtable_count is the count of memtables (gauge). | no | +| `MemtableZombieCount` | memtable_zombie_count is the count of memtables no longer referenced by the current DB state, but still in use by an iterator (gauge). | no | +| `MemtableZombieSize` | memtable_zombie_size is the size, in bytes, of all zombie memtables (gauge). | no | +| `WalLiveCount` | wal_live_count is the count of live WAL files (gauge). | no | +| `WalLiveSize` | wal_live_size is the size, in bytes, of live data in WAL files. With WAL recycling, this value is less than the actual on-disk size of the WAL files (gauge). | no | +| `WalObsoleteCount` | wal_obsolete_count is the count of obsolete WAL files (gauge). | no | +| `WalObsoleteSize` | wal_obsolete_size is the size of obsolete WAL files, in bytes (gauge). | no | +| `WalPhysicalSize` | wal_physical_size is the size, in bytes, of the WAL files on disk (gauge). | no | +| `WalBytesIn` | wal_bytes_in is the number of logical bytes written to the WAL (counter). | no | +| `WalBytesWritten` | wal_bytes_written is the number of bytes written to the WAL (counter). | no | +| `TableObsoleteCount` | table_obsolete_count is the number of tables which are no longer referenced by the current DB state or any open iterators (gauge). | no | +| `TableObsoleteSize` | table_obsolete_size is the size, in bytes, of obsolete tables (gauge). | no | +| `TableZombieCount` | table_zombie_count is the number of tables no longer referenced by the current DB state, but are still in use by an open iterator (gauge). | no | +| `TableZombieSize` | table_zombie_size is the size, in bytes, of zombie tables (gauge). | no | +| `RangeKeySetsCount` | range_key_sets_count is the approximate count of internal range key sets in the store. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `captured_index_usage_stats` + +An event of type `captured_index_usage_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `TotalReadCount` | TotalReadCount is the number of times the index has been read. | no | +| `LastRead` | LastRead is the timestamp at which the index was last read. | no | +| `TableID` | TableID is the ID of the table on which the index was created. This is same as descpb.TableID and is unique within the cluster. | no | +| `IndexID` | IndexID is the ID of the index within the scope of the given table. | no | +| `DatabaseName` | DatabaseName is the name of the database in which the index was created. | no | +| `TableName` | TableName is the name of the table on which the index was created. | no | +| `IndexName` | IndexName is the name of the index within the scope of the given table. | no | +| `IndexType` | IndexType is the type of the index. Index types include "primary" and "secondary". | no | +| `IsUnique` | IsUnique indicates if the index has a UNIQUE constraint. | no | +| `IsInverted` | IsInverted indicates if the index is an inverted index. | no | +| `CreatedAt` | CreatedAt is the timestamp at which the index was created. | no | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `m_v_c_c_iterator_stats` + +Internal storage iteration statistics for a single execution. + + +| Field | Description | Sensitive | +|--|--|--| +| `StepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `StepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `BlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `BlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `KeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `ValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | + + + +### `recovery_event` + +An event of type `recovery_event` is an event that is logged on every invocation of BACKUP, +RESTORE, and on every BACKUP schedule creation, with the appropriate subset +of fields populated depending on the type of event. This event is is also +logged whenever a BACKUP and RESTORE job completes or fails. + + +| Field | Description | Sensitive | +|--|--|--| +| `RecoveryType` | RecoveryType is the type of recovery described by this event, which is one of - backup - scheduled_backup - create_schedule - restore

It can also be a job event corresponding to the recovery, which is one of - backup_job - scheduled_backup_job - restore_job | no | +| `TargetScope` | TargetScope is the largest scope of the targets that the user is backing up or restoring based on the following order: table < schema < database < full cluster. | no | +| `IsMultiregionTarget` | IsMultiregionTarget is true if any of the targets contain objects with multi-region primitives. | no | +| `TargetCount` | TargetCount is the number of targets the in the BACKUP/RESTORE. | no | +| `DestinationSubdirType` | DestinationSubdirType is - latest: if using the latest subdir - standard: if using a date-based subdir - custom: if using a custom subdir that's not date-based | no | +| `DestinationStorageTypes` | DestinationStorageTypes are the types of storage that the user is backing up to or restoring from. | no | +| `DestinationAuthTypes` | DestinationAuthTypes are the types of authentication methods that the user is using to access the destination storage. | no | +| `IsLocalityAware` | IsLocalityAware indicates if the BACKUP or RESTORE is locality aware. | no | +| `AsOfInterval` | AsOfInterval is the time interval in nanoseconds between the statement timestamp and the timestamp resolved by the AS OF SYSTEM TIME expression. The interval is expressed in nanoseconds. | no | +| `WithRevisionHistory` | WithRevisionHistory is true if the BACKUP includes revision history. | no | +| `HasEncryptionPassphrase` | HasEncryptionPassphrase is true if the user provided an encryption passphrase to encrypt/decrypt their backup. | no | +| `KMSType` | KMSType is the type of KMS the user is using to encrypt/decrypt their backup. | no | +| `KMSCount` | KMSCount is the number of KMS the user is using. | no | +| `Options` | Options contain all the names of the options specified by the user in the BACKUP or RESTORE statement. For options that are accompanied by a value, only those with non-empty values will be present.

It's important to note that there are no option values anywhere in the event payload. Future changes to telemetry should refrain from adding values to the payload unless they are properly redacted. | no | +| `DebugPauseOn` | DebugPauseOn is the type of event that the restore should pause on for debugging purposes. Currently only "error" is supported. | no | +| `JobID` | JobID is the ID of the BACKUP/RESTORE job. | no | +| `ResultStatus` | ResultStatus indicates whether the job succeeded or failed. | no | +| `ErrorText` | ErrorText is the text of the error that caused the job to fail. | partially | +| `RecurringCron` | RecurringCron is the crontab for the incremental backup. | no | +| `FullBackupCron` | FullBackupCron is the crontab for the full backup. | no | +| `CustomFirstRunTime` | CustomFirstRunTime is the timestamp for the user configured first run time. Expressed as nanoseconds since the Unix epoch. | no | +| `OnExecutionFailure` | OnExecutionFailure describes the desired behavior if the schedule fails to execute. | no | +| `OnPreviousRunning` | OnPreviousRunning describes the desired behavior if the previously scheduled BACKUP is still running. | no | +| `IgnoreExistingBackup` | IgnoreExistingBackup is true iff the BACKUP schedule should still be created even if a backup is already present in its destination. | no | +| `ApplicationName` | The application name for the session where recovery event was created. | no | +| `NumRows` | NumRows is the number of rows successfully imported, backed up or restored. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `sampled_exec_stats` + +An event of type `sampled_exec_stats` contains execution statistics that apply to both statements +and transactions. These stats as a whole are collected using a sampling approach. +These exec stats are meant to contain the same fields as ExecStats in +apps_stats.proto but are for a single execution rather than aggregated executions. +Fields in this struct should be updated in sync with apps_stats.proto. + + +| Field | Description | Sensitive | +|--|--|--| +| `NetworkBytes` | NetworkBytes collects the number of bytes sent over the network by DistSQL components. | no | +| `MaxMemUsage` | MaxMemUsage collects the maximum memory usage that occurred on a node. | no | +| `ContentionTime` | ContentionTime collects the time in seconds statements in the transaction spent contending. | no | +| `NetworkMessages` | NetworkMessages collects the number of messages that were sent over the network by DistSQL components. | no | +| `MaxDiskUsage` | MaxDiskUsage collects the maximum temporary disk usage that occurred. This is set in cases where a query had to spill to disk, e.g. when performing a large sort where not all of the tuples fit in memory. | no | +| `CPUSQLNanos` | CPUSQLNanos collects the CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `MVCCIteratorStats` | Internal storage iteration statistics. | yes | + + + +### `sampled_query` + +An event of type `sampled_query` is the SQL query event logged to the telemetry channel. It +contains common SQL event/execution details. + + +| Field | Description | Sensitive | +|--|--|--| +| `SkippedQueries` | skipped_queries indicate how many SQL statements were not considered for sampling prior to this one. If the field is omitted, or its value is zero, this indicates that no statement was omitted since the last event. | no | +| `CostEstimate` | Cost of the query as estimated by the optimizer. | no | +| `Distribution` | The distribution of the DistSQL query plan (local, full, or partial). | no | +| `PlanGist` | The query's plan gist bytes as a base64 encoded string. | no | +| `SessionID` | SessionID is the ID of the session that initiated the query. | no | +| `Database` | Name of the database that initiated the query. | no | +| `StatementID` | Statement ID of the query. | no | +| `TransactionID` | Transaction ID of the query. | no | +| `MaxFullScanRowsEstimate` | Maximum number of rows scanned by a full scan, as estimated by the optimizer. | no | +| `TotalScanRowsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer. | no | +| `OutputRowsEstimate` | The number of rows output by the query, as estimated by the optimizer. | no | +| `StatsAvailable` | Whether table statistics were available to the optimizer when planning the query. | no | +| `NanosSinceStatsCollected` | The maximum number of nanoseconds that have passed since stats were collected on any table scanned by this query. | no | +| `BytesRead` | The number of bytes read from disk. | no | +| `RowsRead` | The number of rows read from disk. | no | +| `RowsWritten` | The number of rows written. | no | +| `InnerJoinCount` | The number of inner joins in the query plan. | no | +| `LeftOuterJoinCount` | The number of left (or right) outer joins in the query plan. | no | +| `FullOuterJoinCount` | The number of full outer joins in the query plan. | no | +| `SemiJoinCount` | The number of semi joins in the query plan. | no | +| `AntiJoinCount` | The number of anti joins in the query plan. | no | +| `IntersectAllJoinCount` | The number of intersect all joins in the query plan. | no | +| `ExceptAllJoinCount` | The number of except all joins in the query plan. | no | +| `HashJoinCount` | The number of hash joins in the query plan. | no | +| `CrossJoinCount` | The number of cross joins in the query plan. | no | +| `IndexJoinCount` | The number of index joins in the query plan. | no | +| `LookupJoinCount` | The number of lookup joins in the query plan. | no | +| `MergeJoinCount` | The number of merge joins in the query plan. | no | +| `InvertedJoinCount` | The number of inverted joins in the query plan. | no | +| `ApplyJoinCount` | The number of apply joins in the query plan. | no | +| `ZigZagJoinCount` | The number of zig zag joins in the query plan. | no | +| `ContentionNanos` | The duration of time in nanoseconds that the query experienced contention. | no | +| `Regions` | The regions of the nodes where SQL processors ran. | no | +| `NetworkBytesSent` | The number of network bytes by DistSQL components. | no | +| `MaxMemUsage` | The maximum amount of memory usage by nodes for this query. | no | +| `MaxDiskUsage` | The maximum amount of disk usage by nodes for this query. | no | +| `KVBytesRead` | The number of bytes read at the KV layer for this query. | no | +| `KVPairsRead` | The number of key-value pairs read at the KV layer for this query. | no | +| `KVRowsRead` | The number of rows read at the KV layer for this query. | no | +| `NetworkMessages` | The number of network messages sent by nodes for this query by DistSQL components. | no | +| `IndexRecommendations` | Generated index recommendations for this query. | no | +| `ScanCount` | The number of scans in the query plan. | no | +| `ScanWithStatsCount` | The number of scans using statistics (including forecasted statistics) in the query plan. | no | +| `ScanWithStatsForecastCount` | The number of scans using forecasted statistics in the query plan. | no | +| `TotalScanRowsWithoutForecastsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer without using forecasts. | no | +| `NanosSinceStatsForecasted` | The greatest quantity of nanoseconds that have passed since the forecast time (or until the forecast time, if it is in the future, in which case it will be negative) for any table with forecasted stats scanned by this query. | no | +| `Indexes` | The list of indexes used by this query. | no | +| `CpuTimeNanos` | Collects the cumulative CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `KvGrpcCalls` | The number of grpc calls done to get data form KV nodes | no | +| `KvTimeNanos` | Cumulated time spent waiting for a KV request. This includes disk IO time and potentially network time (if any of the keys are not local). | no | +| `ServiceLatencyNanos` | The time to service the query, from start of parse to end of execute. | no | +| `OverheadLatencyNanos` | The difference between service latency and the sum of parse latency + plan latency + run latency . | no | +| `RunLatencyNanos` | The time to run the query and fetch or compute the result rows. | no | +| `PlanLatencyNanos` | The time to transform the AST into a logical query plan. | no | +| `IdleLatencyNanos` | The time between statement executions in a transaction | no | +| `ParseLatencyNanos` | The time to transform the SQL string into an abstract syntax tree (AST). | no | +| `MvccStepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccStepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccBlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `MvccBlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `MvccKeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `SchemaChangerMode` | SchemaChangerMode is the mode that was used to execute the schema change, if any. | no | +| `SQLInstanceIDs` | SQLInstanceIDs is a list of all the SQL instances used in this statement's execution. | no | +| `KVNodeIDs` | KVNodeIDs is a list of all the KV nodes used in this statement's execution. | no | +| `StatementFingerprintID` | Statement fingerprint ID of the query. | no | +| `UsedFollowerRead` | UsedFollowerRead indicates whether at least some reads were served by the follower replicas. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sampled_transaction` + +An event of type `sampled_transaction` is the event logged to telemetry at the end of transaction execution. + + +| Field | Description | Sensitive | +|--|--|--| +| `User` | User is the user account that triggered the transaction. The special usernames `root` and `node` are not considered sensitive. | depends | +| `ApplicationName` | ApplicationName is the application name for the session where the transaction was executed. This is included in the event to ease filtering of logging output by application. | no | +| `TxnCounter` | TxnCounter is the sequence number of the SQL transaction inside its session. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `TransactionID` | TransactionID is the id of the transaction. | no | +| `Committed` | Committed indicates if the transaction committed successfully. We want to include this value even if it is false. | no | +| `ImplicitTxn` | ImplicitTxn indicates if the transaction was an implicit one. We want to include this value even if it is false. | no | +| `StartTimeUnixNanos` | StartTimeUnixNanos is the time the transaction was started. Expressed as unix time in nanoseconds. | no | +| `EndTimeUnixNanos` | EndTimeUnixNanos the time the transaction finished (either committed or aborted). Expressed as unix time in nanoseconds. | no | +| `ServiceLatNanos` | ServiceLatNanos is the time to service the whole transaction, from start to end of execution. | no | +| `SQLSTATE` | SQLSTATE is the SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | ErrorText is the text of the error if any. | partially | +| `NumRetries` | NumRetries is the number of time when the txn was retried automatically by the server. | no | +| `LastAutoRetryReason` | LastAutoRetryReason is a string containing the reason for the last automatic retry. | partially | +| `NumRows` | NumRows is the total number of rows returned across all statements. | no | +| `RetryLatNanos` | RetryLatNanos is the amount of time spent retrying the transaction. | no | +| `CommitLatNanos` | CommitLatNanos is the amount of time spent committing the transaction after all statement operations. | no | +| `IdleLatNanos` | IdleLatNanos is the amount of time spent waiting for the client to send statements while the transaction is open. | no | +| `BytesRead` | BytesRead is the number of bytes read from disk. | no | +| `RowsRead` | RowsRead is the number of rows read from disk. | no | +| `RowsWritten` | RowsWritten is the number of rows written to disk. | no | +| `SampledExecStats` | SampledExecStats is a nested field containing execution statistics. This field will be omitted if the stats were not sampled. | yes | +| `SkippedTransactions` | SkippedTransactions is the number of transactions that were skipped as part of sampling prior to this one. We only count skipped transactions when telemetry logging is enabled and the sampling mode is set to "transaction". | no | +| `TransactionFingerprintID` | TransactionFingerprintID is the fingerprint ID of the transaction. This can be used to find the transaction in the console. | no | +| `StatementFingerprintIDs` | StatementFingerprintIDs is an array of statement fingerprint IDs belonging to this transaction. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_descriptor` + +An event of type `schema_descriptor` is an event for schema telemetry, whose purpose is +to take periodic snapshots of the cluster's SQL schema and publish them in +the telemetry log channel. For all intents and purposes, the data in such a +snapshot can be thought of the outer join of certain system tables: +namespace, descriptor, and at some point perhaps zones, etc. + +Snapshots are too large to conveniently be published as a single log event, +so instead they're broken down into SchemaDescriptor events which +contain the data in one record of this outer join projection. These events +are prefixed by a header (a SchemaSnapshotMetadata event). + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of the snapshot that this event is part of. | no | +| `ParentDatabaseID` | ParentDatabaseID matches the same key column in system.namespace. | no | +| `ParentSchemaID` | ParentSchemaID matches the same key column in system.namespace. | no | +| `Name` | Name matches the same key column in system.namespace. | no | +| `DescID` | DescID matches the 'id' column in system.namespace and system.descriptor. | no | +| `Desc` | Desc matches the 'descriptor' column in system.descriptor. Some contents of the descriptor may be redacted to prevent leaking PII. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_snapshot_metadata` + +An event of type `schema_snapshot_metadata` is an event describing a schema snapshot, which +is a set of SchemaDescriptor messages sharing the same SnapshotID. + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of this snapshot. | no | +| `NumRecords` | NumRecords is how many SchemaDescriptor events are in the snapshot. | no | +| `AsOfTimestamp` | AsOfTimestamp is when the snapshot was taken. This is equivalent to the timestamp given in the AS OF SYSTEM TIME clause when querying the namespace and descriptor tables in the system database. Expressed as nanoseconds since the Unix epoch. | no | +| `Errors` | Errors records any errors encountered when post-processing this snapshot, which includes the redaction of any potential PII. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Zone config events + +Events in this category pertain to zone configuration changes on +the SQL schema or system ranges. + +When zone configs apply to individual tables or other objects in a +SQL logical schema, they are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these zone config events are preserved +in each tenant's own `system.eventlog` table. + +When they apply to cluster-level ranges (e.g., the system zone config), +they are stored in the system tenant's own `system.eventlog` table. + +Events in this category are logged to the `OPS` channel. + + +### `remove_zone_config` + +An event of type `remove_zone_config` is recorded when a zone config is removed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `set_zone_config` + +An event of type `set_zone_config` is recorded when a zone config is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `ResolvedOldConfig` | The string representation of the resolved old zone config. This is not necessarily the same as the zone config that was previously set -- as it includes the resolved values of the zone config options. In other words, a zone config that hasn't been properly "set" yet (and inherits from its parent) will have a resolved_old_config that has details of the values it inherits from its parent. This is particularly useful to get a proper diff between the old and new zone config. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + + + + +## Enumeration types + +### `AuthFailReason` + +AuthFailReason is the inventory of possible reasons for an +authentication failure. + + +| Value | Textual alias in code or documentation | Description | +|--|--|--| +| 0 | UNKNOWN | is reported when the reason is unknown. | +| 1 | USER_RETRIEVAL_ERROR | occurs when there was an internal error accessing the principals. | +| 2 | USER_NOT_FOUND | occurs when the principal is unknown. | +| 3 | LOGIN_DISABLED | occurs when the user does not have LOGIN privileges. | +| 4 | METHOD_NOT_FOUND | occurs when no HBA rule matches or the method does not exist. | +| 5 | PRE_HOOK_ERROR | occurs when the authentication handshake encountered a protocol error. | +| 6 | CREDENTIALS_INVALID | occurs when the client-provided credentials were invalid. | +| 7 | CREDENTIALS_EXPIRED | occur when the credentials provided by the client are expired. | +| 8 | NO_REPLICATION_ROLEOPTION | occurs when the connection requires a replication role option, but the user does not have it. | +| 9 | AUTHORIZATION_ERROR | is used for errors during the authorization phase. For example, this would include issues with mapping LDAP groups to SQL roles and granting those roles to the user. | +| 10 | PROVISIONING_ERROR | is used for errors during the user provisioning phase. This would include errors when the transaction to provision the authenticating user failed to execute. | + + + diff --git a/src/current/_includes/cockroach-generated/release-25.3/logformats.md b/src/current/_includes/cockroach-generated/release-25.3/logformats.md new file mode 100644 index 00000000000..89580c9fc15 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.3/logformats.md @@ -0,0 +1,382 @@ + +The supported log output formats are documented below. + + +- [`crdb-v1`](#format-crdb-v1) + +- [`crdb-v1-count`](#format-crdb-v1-count) + +- [`crdb-v1-tty`](#format-crdb-v1-tty) + +- [`crdb-v1-tty-count`](#format-crdb-v1-tty-count) + +- [`crdb-v2`](#format-crdb-v2) + +- [`crdb-v2-tty`](#format-crdb-v2-tty) + +- [`json`](#format-json) + +- [`json-compact`](#format-json-compact) + +- [`json-fluent`](#format-json-fluent) + +- [`json-fluent-compact`](#format-json-fluent-compact) + + + +## Format `crdb-v1` + + +This is a legacy file format used from CockroachDB v1.0. + +Each log entry is emitted using a common prefix, described below, followed by: + +- The logging context tags enclosed between `[` and `]`, if any. It is possible + for this to be omitted if there were no context tags. +- Optionally, a counter column, if the option 'show-counter' is enabled. See below for details. +- the text of the log entry. + +Beware that the text of the log entry can span multiple lines. +The following caveats apply: + +- The text of the log entry can start with text enclosed between `[` and `]`. + If there were no logging tags to start with, it is not possible to distinguish between + logging context tag information and a `[...]` string in the main text of the + log entry. This means that this format is ambiguous. + + To remove this ambiguity, you can use the option 'show-counter'. + +- The text of the log entry can embed arbitrary application-level strings, + including strings that represent log entries. In particular, an accident + of implementation can cause the common entry prefix (described below) + to also appear on a line of its own, as part of the payload of a previous + log entry. There is no automated way to recognize when this occurs. + Care must be taken by a human observer to recognize these situations. + +- The log entry parser provided by CockroachDB to read log files is faulty + and is unable to recognize the aforementioned pitfall; nor can it read + entries larger than 64KiB successfully. Generally, use of this internal + log entry parser is discouraged for entries written with this format. + +See the newer format `crdb-v2` for an alternative +without these limitations. + +### Header lines + +At the beginning of each file, a header is printed using a similar format as +regular log entries. This header reports when the file was created, +which parameters were used to start the server, the server identifiers +if known, and other metadata about the running process. + +- This header appears to be logged at severity `INFO` (with an `I` prefix + at the start of the line) even though it does not really have a severity. +- The header is printed unconditionally even when a filter is configured to + omit entries at the `INFO` level. + +### Common log entry prefix + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker tags counter + +Reminder, the tags may be omitted; and the counter is only printed if the option +'show-counter' is specified. + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (omitted if zero for use by tests). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. | +| line | The line number where the entry originated. | +| marker | Redactability marker ` + redactableIndicator + ` (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. May be absent. | +| counter | The entry counter. Only included if 'show-counter' is enabled. | + +The redactability marker can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. + +If the marker ` + redactableIndicator + ` is present, the remainder of the log entry +contains delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `show-counter` | Whether to include the counter column in the line header. Without it, the format may be ambiguous due to the optionality of tags. | +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v1-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: none` + + +## Format `crdb-v1-tty` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: false` +- `colors: auto` + + +## Format `crdb-v1-tty-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: auto` + + +## Format `crdb-v2` + +This is the main file format used from CockroachDB v21.1. + +Each log entry is emitted using a common prefix, described below, +followed by the text of the log entry. + +### Entry format + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker [tags...] counter cont + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (zero when cannot be determined). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. Also see below. | +| line | The line number where the entry originated. | +| marker | Redactability marker "⋮" (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. See below. | +| counter | The optional entry counter (see below for details). | +| cont | Continuation mark for structured and multi-line entries. See below. | + +The `chan@` prefix before the file name indicates the logging channel, +and is omitted if the channel is `DEV`. + +The file name may be prefixed by the string `(gostd) ` to indicate +that the log entry was produced inside the Go standard library, instead +of a CockroachDB component. Entry parsers must be configured to ignore this prefix +when present. + +`marker` can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. +If the marker "⋮" is present, the remainder of the log entry +contains delimiters (‹...›) +around fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +when log redaction is requested. + +The logging `tags` are enclosed between square brackets `[...]`, +and the syntax `[-]` is used when there are no logging tags +associated with the log entry. + +`counter` is numeric, and is incremented for every +log entry emitted to this sink. (There is thus one counter sequence per +sink.) For entries that do not have a counter value +associated (e.g., header entries in file sinks), the counter position +in the common prefix is empty: `tags` is then +followed by two ASCII space characters, instead of one space; the `counter`, +and another space. The presence of the two ASCII spaces indicates +reliably that no counter was present. + +`cont` is a format/continuation indicator: + +| Continuation indicator | ASCII | Description | +|------------------------|-------|--| +| space | 0x32 | Start of an unstructured entry. | +| equal sign, "=" | 0x3d | Start of a structured entry. | +| exclamation mark, "!" | 0x21 | Start of an embedded stack trace. | +| plus sign, "+" | 0x2b | Continuation of a multi-line entry. The payload contains a newline character at this position. | +| vertical bar | 0x7c | Continuation of a large entry. | + +### Examples + +Example single-line unstructured entry: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 started with engine type ‹2› +~~~ + +Example multi-line unstructured entry: + +~~~ +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 node startup completed: +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 +CockroachDB node starting at 2021-01-16 21:49 (took 0.0s) +~~~ + +Example structured entry: + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventType":"node_restart"} +~~~ + +Example long entries broken up into multiple lines: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.... +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 |aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +~~~ + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventTy... +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 |pe":"node_restart"} +~~~ + +### Backward-compatibility notes + +Entries in this format can be read by most `crdb-v1` log parsers, +in particular the one included in the DB console and +also the [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +facility. + +However, implementers of previous version parsers must +understand that the logging tags field is now always +included, and the lack of logging tags is included +by a tag string set to `[-]`. + +Likewise, the entry counter is now also always included, +and there is a special character after `counter` +to indicate whether the remainder of the line is a +structured entry, or a continuation of a previous entry. + +Finally, in the previous format, structured entries +were prefixed with the string `Structured entry: `. In +the new format, they are prefixed by the `=` continuation +indicator. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v2-tty` + +This format name is an alias for 'crdb-v2' with +the following format option defaults: + +- `colors: auto` + + +## Format `json` + +This format emits log entries as a JSON payload. + +The JSON object is guaranteed to not contain unescaped newlines +or other special characters, and the entry as a whole is followed +by a newline character. This makes the format suitable for +processing over a stream unambiguously. + +Each entry contains at least the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `tag` | `tag` | (Only if the option `fluent-tag: true` is given.) A Fluent tag for the event, formed by the process name and the logging channel. | +| `d` | `datetime` | The pretty-printed date/time of the event timestamp, if enabled via options. | +| `f` | `file` | The name of the source file where the event was emitted. | +| `g` | `goroutine` | The identifier of the goroutine where the event was emitted. | +| `l` | `line` | The line number where the event was emitted in the source. | +| `r` | `redactable` | Whether the payload is redactable (see below for details). | +| `t` | `timestamp` | The timestamp at which the event was emitted on the logging channel. | +| `v` | `version` | The binary version with which the event was generated. | + + +After a couple of *header* entries written at the beginning of each log sink, +all subsequent log entries also contain the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `C` | `channel` | The name of the logging channel where the event was sent. | +| `sev` | `severity` | The severity of the event. | +| `c` | `channel_numeric` | The numeric identifier for the logging channel where the event was sent. | +| `n` | `entry_counter` | The entry number on this logging sink, relative to the last process restart. | +| `s` | `severity_numeric` | The numeric value of the severity of the event. | + + +Additionally, the following fields are conditionally present: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `N` | `node_id` | The node ID where the event was generated, once known. Only reported for single-tenant or KV servers. | +| `x` | `cluster_id` | The cluster ID where the event was generated, once known. Only reported for single-tenant of KV servers. | +| `q` | `instance_id` | The SQL instance ID where the event was generated, once known. | +| `T` | `tenant_id` | The SQL tenant ID where the event was generated, once known. | +| `V` | `tenant_name` | The SQL virtual cluster where the event was generated, once known. | +| `tags` | `tags` | The logging context tags for the entry, if there were context tags. | +| `message` | `message` | For unstructured events, the flat text payload. | +| `event` | `event` | The logging event, if structured (see below for details). | +| `stacks` | `stacks` | Goroutine stacks, for fatal events. | + +When an entry is structured, the `event` field maps to a dictionary +whose structure is one of the documented structured events. See the [reference documentation](eventlog.html) +for structured events for a list of possible payloads. + +When the entry is marked as `redactable`, the `tags`, `message`, and/or `event` payloads +contain delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `datetime-format` | The format to use for the `datetime` field. The value can be one of `none`, `iso8601`/`rfc3339` (synonyms), or `rfc1123`. Default is `none`. | +| `datetime-timezone` | The timezone to use for the `datetime` field. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | +| `tag-style` | The tags to include in the envelope. The value can be `compact` (one letter tags) or `verbose` (long-form tags). Default is `verbose`. | +| `fluent-tag` | Whether to produce an additional field called `tag` for Fluent compatibility. Default is `false`. | + + + +## Format `json-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: false` +- `tag-style: compact` + + +## Format `json-fluent` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: verbose` + + +## Format `json-fluent-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: compact` + + diff --git a/src/current/_includes/cockroach-generated/release-25.3/logging.md b/src/current/_includes/cockroach-generated/release-25.3/logging.md new file mode 100644 index 00000000000..8b628dc2dd9 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.3/logging.md @@ -0,0 +1,179 @@ +## Logging levels (severities) + +### INFO + +The `INFO` severity is used for informational messages that do not +require action. + +### WARNING + +The `WARNING` severity is used for situations which may require special handling, +where normal operation is expected to resume automatically. + +### ERROR + +The `ERROR` severity is used for situations that require special handling, +where normal operation could not proceed as expected. +Other operations can continue mostly unaffected. + +### FATAL + +The `FATAL` severity is used for situations that require an immedate, hard +server shutdown. A report is also sent to telemetry if telemetry +is enabled. + + +## Logging channels + +### `DEV` + +The `DEV` channel is used during development to collect log +details useful for troubleshooting that fall outside the +scope of other channels. It is also the default logging +channel for events not associated with a channel. + +This channel is special in that there are no constraints as to +what may or may not be logged on it. Conversely, users in +production deployments are invited to not collect `DEV` logs in +centralized logging facilities, because they likely contain +sensitive operational data. +See [Configure logs](configure-logs.html#dev-channel). + +### `OPS` + +The `OPS` channel is used to report "point" operational events, +initiated by user operators or automation: + + - Operator or system actions on server processes: process starts, + stops, shutdowns, crashes (if they can be logged), + including each time: command-line parameters, current version being run + - Actions that impact the topology of a cluster: node additions, + removals, decommissions, etc. + - Job-related initiation or termination + - [Cluster setting](cluster-settings.html) changes + - [Zone configuration](configure-replication-zones.html) changes + +### `HEALTH` + +The `HEALTH` channel is used to report "background" operational +events, initiated by CockroachDB or reporting on automatic processes: + + - Current resource usage, including critical resource usage + - Node-node connection events, including connection errors and + gossip details + - Range and table leasing events + - Up- and down-replication, range unavailability + +### `STORAGE` + +The `STORAGE` channel is used to report low-level storage +layer events (RocksDB/Pebble). + +### `SESSIONS` + +The `SESSIONS` channel is used to report client network activity when enabled via +the `server.auth_log.sql_connections.enabled` and/or +`server.auth_log.sql_sessions.enabled` [cluster setting](cluster-settings.html): + + - Connections opened/closed + - Authentication events: logins, failed attempts + - Session and query cancellation + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_SCHEMA` + +The `SQL_SCHEMA` channel is used to report changes to the +SQL logical schema, excluding privilege and ownership changes +(which are reported separately on the `PRIVILEGES` channel) and +zone configuration changes (which go to the `OPS` channel). + +This includes: + + - Database/schema/table/sequence/view/type creation + - Adding/removing/changing table columns + - Changing sequence parameters + +`SQL_SCHEMA` events generally comprise changes to the schema that affect the +functional behavior of client apps using stored objects. + +### `USER_ADMIN` + +The `USER_ADMIN` channel is used to report changes +in users and roles, including: + + - Users added/dropped + - Changes to authentication credentials (e.g., passwords, validity, etc.) + - Role grants/revocations + - Role option grants/revocations + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `PRIVILEGES` + +The `PRIVILEGES` channel is used to report data +authorization changes, including: + + - Privilege grants/revocations on database, objects, etc. + - Object ownership changes + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SENSITIVE_ACCESS` + +The `SENSITIVE_ACCESS` channel is used to report SQL +data access to sensitive data: + + - Data access audit events (when table audit is enabled via + [ALTER TABLE ... EXPERIMENTAL_AUDIT](alter-table.html#experimental_audit)) + - Data access audit events (when role-based audit is enabled via + [`sql.log.user_audit` cluster setting](role-based-audit-logging.html#syntax-of-audit-settings)) + - SQL statements executed by users with the admin role + - Operations that write to system tables + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_EXEC` + +The `SQL_EXEC` channel is used to report SQL execution on +behalf of client connections: + + - Logical SQL statement executions (when enabled via the + `sql.log.all_statements.enabled` [cluster setting](cluster-settings.html)) + - uncaught Go panic errors during the execution of a SQL statement. + +### `SQL_PERF` + +The `SQL_PERF` channel is used to report SQL executions +that are marked as "out of the ordinary" +to facilitate performance investigations. +This includes the SQL "slow query log". + +Arguably, this channel overlaps with `SQL_EXEC`. +However, we keep both channels separate for backward compatibility +with versions prior to v21.1, where the corresponding events +were redirected to separate files. + +### `SQL_INTERNAL_PERF` + +The `SQL_INTERNAL_PERF` channel is like the `SQL_PERF` channel, but is aimed at +helping developers of CockroachDB itself. It exists as a separate +channel so as to not pollute the `SQL_PERF` logging output with +internal troubleshooting details. + +### `TELEMETRY` + +The `TELEMETRY` channel reports telemetry events. Telemetry events describe +feature usage within CockroachDB and anonymizes any application- +specific data. + +### `KV_DISTRIBUTION` + +The `KV_DISTRIBUTION` channel is used to report data distribution events, such as moving +replicas between stores in the cluster, or adding (removing) replicas to +ranges. + diff --git a/src/current/_includes/cockroach-generated/release-25.3/settings/settings.html b/src/current/_includes/cockroach-generated/release-25.3/settings/settings.html new file mode 100644 index 00000000000..7b8d5c09fb4 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.3/settings/settings.html @@ -0,0 +1,380 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingTypeDefaultDescriptionSupported Deployments
admission.disk_bandwidth_tokens.elastic.enabled
booleantruewhen true, and provisioned bandwidth for the disk corresponding to a store is configured, tokens for elastic work will be limited if disk bandwidth becomes a bottleneckAdvanced/Self-Hosted
admission.epoch_lifo.enabled
booleanfalsewhen true, epoch-LIFO behavior is enabled when there is significant delay in admissionBasic/Standard/Advanced/Self-Hosted
admission.epoch_lifo.epoch_closing_delta_duration
duration5msthe delta duration before closing an epoch, for epoch-LIFO admission control orderingBasic/Standard/Advanced/Self-Hosted
admission.epoch_lifo.epoch_duration
duration100msthe duration of an epoch, for epoch-LIFO admission control orderingBasic/Standard/Advanced/Self-Hosted
admission.epoch_lifo.queue_delay_threshold_to_switch_to_lifo
duration105msthe queue delay encountered by a (tenant,priority) for switching to epoch-LIFO orderingBasic/Standard/Advanced/Self-Hosted
admission.kv.enabled
booleantruewhen true, work performed by the KV layer is subject to admission controlAdvanced/Self-Hosted
admission.sql_kv_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a KV response is subject to admission controlBasic/Standard/Advanced/Self-Hosted
admission.sql_sql_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a DistSQL response is subject to admission controlBasic/Standard/Advanced/Self-Hosted
bulkio.backup.deprecated_full_backup_with_subdir.enabled
booleanfalsewhen true, a backup command with a user specified subdirectory will create a full backup at the subdirectory if no backup already exists at that subdirectoryBasic/Standard/Advanced/Self-Hosted
bulkio.backup.file_size
byte size128 MiBtarget size for individual data files produced during BACKUPBasic/Standard/Advanced/Self-Hosted
bulkio.backup.read_timeout
duration5m0samount of time after which a read attempt is considered timed out, which causes the backup to failBasic/Standard/Advanced/Self-Hosted
bulkio.backup.read_with_priority_after
duration1m0samount of time since the read-as-of time above which a BACKUP should use priority when retrying readsBasic/Standard/Advanced/Self-Hosted
physical_replication.consumer.minimum_flush_interval
(alias: bulkio.stream_ingestion.minimum_flush_interval)
duration5sthe minimum timestamp between flushes; flushes may still occur if internal buffers fill upAdvanced/Self-Hosted
changefeed.aggregator.flush_jitter
float0.1jitter aggregator flushes as a fraction of min_checkpoint_frequency. This setting has no effect if min_checkpoint_frequency is set to 0.Basic/Standard/Advanced/Self-Hosted
changefeed.backfill.concurrent_scan_requests
integer0number of concurrent scan requests per node issued during a backfillBasic/Standard/Advanced/Self-Hosted
changefeed.backfill.scan_request_size
integer524288the maximum number of bytes returned by each scan requestBasic/Standard/Advanced/Self-Hosted
changefeed.batch_reduction_retry.enabled
(alias: changefeed.batch_reduction_retry_enabled)
booleanfalseif true, kafka changefeeds upon erroring on an oversized batch will attempt to resend the messages with progressively lower batch sizesBasic/Standard/Advanced/Self-Hosted
changefeed.default_range_distribution_strategy
enumerationdefaultconfigures how work is distributed among nodes for a given changefeed. for the most balanced distribution, use `balanced_simple`. changing this setting will not override locality restrictions [default = 0, balanced_simple = 1]Basic/Standard/Advanced/Self-Hosted
changefeed.event_consumer_worker_queue_size
integer16if changefeed.event_consumer_workers is enabled, this setting sets the maxmimum number of events which a worker can bufferBasic/Standard/Advanced/Self-Hosted
changefeed.event_consumer_workers
integer0the number of workers to use when processing events: <0 disables, 0 assigns a reasonable default, >0 assigns the setting value. for experimental/core changefeeds and changefeeds using parquet format, this is disabledBasic/Standard/Advanced/Self-Hosted
changefeed.fast_gzip.enabled
booleantrueuse fast gzip implementationBasic/Standard/Advanced/Self-Hosted
changefeed.span_checkpoint.lag_threshold
(alias: changefeed.frontier_highwater_lag_checkpoint_threshold)
duration10m0sthe amount of time a changefeed's lagging (slowest) spans must lag behind its leading (fastest) spans before a span-level checkpoint to save leading span progress is written; if 0, span-level checkpoints due to lagging spans is disabledBasic/Standard/Advanced/Self-Hosted
changefeed.kafka_v2_error_details.enabled
booleantrueif enabled, Kafka v2 sinks will include the message key, size, and MVCC timestamp in message too large errorsBasic/Standard/Advanced/Self-Hosted
changefeed.memory.per_changefeed_limit
byte size512 MiBcontrols amount of data that can be buffered per changefeedBasic/Standard/Advanced/Self-Hosted
changefeed.resolved_timestamp.min_update_interval
(alias: changefeed.min_highwater_advance)
duration0sminimum amount of time that must have elapsed since the last time a changefeed's resolved timestamp was updated before it is eligible to be updated again; default of 0 means no minimum interval is enforced but updating will still be limited by the average time it takes to checkpoint progressBasic/Standard/Advanced/Self-Hosted
changefeed.node_throttle_config
stringspecifies node level throttling configuration for all changefeeedsBasic/Standard/Advanced/Self-Hosted
changefeed.protect_timestamp.max_age
duration96h0m0sfail the changefeed if the protected timestamp age exceeds this threshold; 0 disables expirationBasic/Standard/Advanced/Self-Hosted
changefeed.protect_timestamp_interval
duration10m0scontrols how often the changefeed forwards its protected timestamp to the resolved timestampBasic/Standard/Advanced/Self-Hosted
changefeed.schema_feed.read_with_priority_after
duration1m0sretry with high priority if we were not able to read descriptors for too long; 0 disablesBasic/Standard/Advanced/Self-Hosted
changefeed.sink_io_workers
integer0the number of workers used by changefeeds when sending requests to the sink (currently the batching versions of webhook, pubsub, and kafka sinks that are enabled by changefeed.new_<sink type>_sink_enabled only): <0 disables, 0 assigns a reasonable default, >0 assigns the setting valueBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.concurrent_upload_buffers
integer1controls the number of concurrent buffers that will be used by the Azure client when uploading chunks.Each buffer can buffer up to cloudstorage.write_chunk.size of memory during an uploadBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.gs.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.gs.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.gs.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.gs.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.custom_ca
stringcustom root CA (appended to system's default CAs) for verifying certificates when interacting with HTTPS storageBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nodelocal.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nodelocal.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nodelocal.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nodelocal.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nullsink.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nullsink.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nullsink.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nullsink.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.s3.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.s3.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.s3.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.s3.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.timeout
duration10m0sthe timeout for import/export storage operationsBasic/Standard/Advanced/Self-Hosted
cloudstorage.userfile.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.userfile.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.userfile.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.userfile.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cluster.auto_upgrade.enabled
booleantruedisable automatic cluster version upgrade until resetBasic/Standard/Advanced/Self-Hosted
cluster.organization
stringorganization nameAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
cluster.preserve_downgrade_option
stringdisable (automatic or manual) cluster version upgrade from the specified version until resetBasic/Standard/Advanced/Self-Hosted
debug.zip.redact_addresses.enabled
booleanfalseenables the redaction of hostnames and ip addresses in debug zipBasic/Standard/Advanced/Self-Hosted
diagnostics.active_query_dumps.enabled
booleantrueexperimental: enable dumping of anonymized active queries to disk when node is under memory pressureAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
diagnostics.forced_sql_stat_reset.interval
duration2h0m0sinterval after which the reported SQL Stats are reset even if not collected by telemetry reporter. It has a max value of 24H.Basic/Standard/Advanced/Self-Hosted
diagnostics.memory_monitoring_dumps.enabled
booleantrueenable dumping of memory monitoring state at the same time as heap profiles are takenAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
diagnostics.reporting.enabled
booleantrueenable reporting diagnostic metrics to cockroach labs, but is ignored for Trial or Free licensesBasic/Standard/Advanced/Self-Hosted
diagnostics.reporting.interval
duration1h0m0sinterval at which diagnostics data should be reportedBasic/Standard/Advanced/Self-Hosted
enterprise.license
stringthe encoded cluster licenseAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
external.graphite.endpoint
stringif nonempty, push server metrics to the Graphite or Carbon server at the specified host:portBasic/Standard/Advanced/Self-Hosted
external.graphite.interval
duration10sthe interval at which metrics are pushed to Graphite (if enabled)Basic/Standard/Advanced/Self-Hosted
feature.backup.enabled
booleantrueset to true to enable backups, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.changefeed.enabled
booleantrueset to true to enable changefeeds, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.export.enabled
booleantrueset to true to enable exports, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.import.enabled
booleantrueset to true to enable imports, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.infer_rbr_region_col_using_constraint.enabled
booleanfalseset to true to enable looking up the region column via a foreign key constraint in a REGIONAL BY ROW table, false to disable; default is falseBasic/Standard/Advanced/Self-Hosted
feature.restore.enabled
booleantrueset to true to enable restore, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.schema_change.enabled
booleantrueset to true to enable schema changes, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.stats.enabled
booleantrueset to true to enable CREATE STATISTICS/ANALYZE, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.vector_index.enabled
booleanfalseset to true to enable vector indexes, false to disable; default is falseBasic/Standard/Advanced/Self-Hosted
jobs.retention_time
duration336h0m0sthe amount of time for which records for completed jobs are retainedBasic/Standard/Advanced/Self-Hosted
kv.allocator.lease_rebalance_threshold
float0.05minimum fraction away from the mean a store's lease count can be before it is considered for lease-transfersAdvanced/Self-Hosted
kv.allocator.load_based_lease_rebalancing.enabled
booleantrueset to enable rebalancing of range leases based on load and latencyAdvanced/Self-Hosted
kv.allocator.load_based_rebalancing
enumerationleases and replicaswhether to rebalance based on the distribution of load across stores [off = 0, leases = 1, leases and replicas = 2]Advanced/Self-Hosted
kv.allocator.load_based_rebalancing.objective
enumerationcpuwhat objective does the cluster use to rebalance; if set to `qps` the cluster will attempt to balance qps among stores, if set to `cpu` the cluster will attempt to balance cpu usage among stores [qps = 0, cpu = 1]Advanced/Self-Hosted
kv.allocator.load_based_rebalancing_interval
duration1m0sthe rough interval at which each store will check for load-based lease / replica rebalancing opportunitiesAdvanced/Self-Hosted
kv.allocator.qps_rebalance_threshold
float0.1minimum fraction away from the mean a store's QPS (such as queries per second) can be before it is considered overfull or underfullAdvanced/Self-Hosted
kv.allocator.range_rebalance_threshold
float0.05minimum fraction away from the mean a store's range count can be before it is considered overfull or underfullAdvanced/Self-Hosted
kv.allocator.store_cpu_rebalance_threshold
float0.1minimum fraction away from the mean a store's cpu usage can be before it is considered overfull or underfullAdvanced/Self-Hosted
kv.bulk_io_write.max_rate
byte size1.0 TiBthe rate limit (bytes/sec) to use for writes to disk on behalf of bulk io opsAdvanced/Self-Hosted
kv.bulk_io_write.min_capacity_remaining_fraction
float0.05remaining store capacity fraction below which bulk ingestion requests are rejectedAdvanced/Self-Hosted
kv.bulk_sst.max_allowed_overage
byte size64 MiBif positive, allowed size in excess of target size for SSTs from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryAdvanced/Self-Hosted
kv.bulk_sst.target_size
byte size16 MiBtarget size for SSTs emitted from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.follower_reads.enabled
(alias: kv.closed_timestamp.follower_reads_enabled)
booleantrueallow (all) replicas to serve consistent historical reads based on closed timestamp informationAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.lead_for_global_reads_auto_tune.enabled
booleanfalseif enabled, observed network latency between leaseholders and their furthest follower will be used to adjust closed timestamp policies for rangesranges configured to serve global reads. kv.closed_timestamp.lead_for_global_reads_override takes precedence if set.Advanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.lead_for_global_reads_override
duration0sif nonzero, overrides the lead time that global_read ranges use to publish closed timestampsAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.side_transport_interval
duration200msthe interval at which the closed timestamp side-transport attempts to advance each range's closed timestamp; set to 0 to disable the side-transportAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.target_duration
duration3sif nonzero, attempt to provide closed timestamp notifications for timestamps trailing cluster time by approximately this durationAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.dist_sender.circuit_breaker.cancellation.enabled
booleantruewhen enabled, in-flight requests will be cancelled when the circuit breaker tripsBasic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breaker.cancellation.write_grace_period
duration10show long after the circuit breaker trips to cancel write requests (these can't retry internally, so should be long enough to allow quorum/lease recovery)Basic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breaker.probe.interval
duration3sinterval between replica probesBasic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breaker.probe.threshold
duration3sduration of errors or stalls after which a replica will be probedBasic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breaker.probe.timeout
duration3stimeout for replica probesBasic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breakers.mode
enumerationliveness range onlyset of ranges to trip circuit breakers for failing or stalled replicas [no ranges = 0, liveness range only = 1, all ranges = 2]Basic/Standard/Advanced/Self-Hosted
kv.lease_transfer_read_summary.global_budget
byte size0 Bcontrols the maximum number of bytes that will be used to summarize the global segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Advanced/Self-Hosted
kv.lease_transfer_read_summary.local_budget
byte size4.0 MiBcontrols the maximum number of bytes that will be used to summarize the local segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Advanced/Self-Hosted
kv.log_range_and_node_events.enabled
booleantrueset to true to transactionally log range events (e.g., split, merge, add/remove voter/non-voter) into system.rangelogand node join and restart events into system.eventologAdvanced/Self-Hosted
kv.protectedts.reconciliation.interval
duration5m0sthe frequency for reconciling jobs with protected timestamp recordsAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.raft.leader_fortification.fraction_enabled
float1controls the fraction of ranges for which the raft leader fortification protocol is enabled. Leader fortification is needed for a range to use a Leader lease. Set to 0.0 to disable leader fortification and, by extension, Leader leases. Set to 1.0 to enable leader fortification for all ranges and, by extension, use Leader leases for all ranges which do not require expiration-based leases. Set to a value between 0.0 and 1.0 to gradually roll out Leader leases across the ranges in a cluster.Advanced/Self-Hosted
kv.range.range_size_hard_cap
byte size8.0 GiBhard cap on the maximum size a range is allowed to grow to withoutsplitting before writes to the range are blocked. Takes precedence over all other configurationsAdvanced/Self-Hosted
kv.range_split.by_load.enabled
(alias: kv.range_split.by_load_enabled)
booleantrueallow automatic splits of ranges based on where load is concentratedAdvanced/Self-Hosted
kv.range_split.load_cpu_threshold
duration500msthe CPU use per second over which, the range becomes a candidate for load based splittingAdvanced/Self-Hosted
kv.range_split.load_qps_threshold
integer2500the QPS over which, the range becomes a candidate for load based splittingAdvanced/Self-Hosted
kv.rangefeed.client.stream_startup_rate
integer100controls the rate per second the client will initiate new rangefeed stream for a single range; 0 implies unlimitedBasic/Standard/Advanced/Self-Hosted
kv.rangefeed.closed_timestamp_refresh_interval
duration3sthe interval at which closed-timestamp updatesare delivered to rangefeeds; set to 0 to use kv.closed_timestamp.side_transport_intervalAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.rangefeed.enabled
booleanfalseif set, rangefeed registration is enabledAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.replica_circuit_breaker.slow_replication_threshold
duration1m0sduration after which slow proposals trip the per-Replica circuit breaker (zero duration disables breakers)Advanced/Self-Hosted
kv.replica_raft.leaderless_unavailable_threshold
duration1m0sduration after which leaderless replicas is considered unavailable. Set to 0 to disable leaderless replica availability checksAdvanced/Self-Hosted
kv.replica_stats.addsst_request_size_factor
integer50000the divisor that is applied to addsstable request sizes, then recorded in a leaseholders QPS; 0 means all requests are treated as cost 1Advanced/Self-Hosted
kv.replication_reports.interval
duration1m0sthe frequency for generating the replication_constraint_stats, replication_stats_report and replication_critical_localities reports (set to 0 to disable)Advanced/Self-Hosted
kv.snapshot_rebalance.max_rate
byte size32 MiBthe rate limit (bytes/sec) to use for rebalance and upreplication snapshotsAdvanced/Self-Hosted
kv.transaction.max_intents_and_locks
integer0maximum count of inserts or durable locks for a single transactions, 0 to disableBasic/Standard/Advanced/Self-Hosted
kv.transaction.max_intents_bytes
integer4194304maximum number of bytes used to track locks in transactionsBasic/Standard/Advanced/Self-Hosted
kv.transaction.max_refresh_spans_bytes
integer4194304maximum number of bytes used to track refresh spans in serializable transactionsBasic/Standard/Advanced/Self-Hosted
kv.transaction.randomized_anchor_key.enabled
booleanfalsedictates whether a transactions anchor key is randomized or notBasic/Standard/Advanced/Self-Hosted
kv.transaction.reject_over_max_intents_budget.enabled
booleanfalseif set, transactions that exceed their lock tracking budget (kv.transaction.max_intents_bytes) are rejected instead of having their lock spans imprecisely compressedBasic/Standard/Advanced/Self-Hosted
kv.transaction.write_pipelining.locking_reads.enabled
booleantrueif enabled, transactional locking reads are pipelined through Raft consensusBasic/Standard/Advanced/Self-Hosted
kv.transaction.write_pipelining.ranged_writes.enabled
booleantrueif enabled, transactional ranged writes are pipelined through Raft consensusBasic/Standard/Advanced/Self-Hosted
kv.transaction.write_pipelining.enabled
(alias: kv.transaction.write_pipelining_enabled)
booleantrueif enabled, transactional writes are pipelined through Raft consensusBasic/Standard/Advanced/Self-Hosted
kv.transaction.write_pipelining.max_batch_size
(alias: kv.transaction.write_pipelining_max_batch_size)
integer128if non-zero, defines that maximum size batch that will be pipelined through Raft consensusBasic/Standard/Advanced/Self-Hosted
kvadmission.store.provisioned_bandwidth
byte size0 Bif set to a non-zero value, this is used as the provisioned bandwidth (in bytes/s), for each store. It can be overridden on a per-store basis using the --store flag. Note that setting the provisioned bandwidth to a positive value may enable disk bandwidth based admission control, since admission.disk_bandwidth_tokens.elastic.enabled defaults to trueAdvanced/Self-Hosted
kvadmission.store.snapshot_ingest_bandwidth_control.enabled
booleantrueif set to true, snapshot ingests will be subject to disk write control in ACAdvanced/Self-Hosted
obs.tablemetadata.automatic_updates.enabled
booleanfalseenables automatic updates of the table metadata cache system.table_metadataBasic/Standard/Advanced/Self-Hosted
obs.tablemetadata.data_valid_duration
duration20m0sthe duration for which the data in system.table_metadata is considered validBasic/Standard/Advanced/Self-Hosted
schedules.backup.gc_protection.enabled
booleantrueenable chaining of GC protection across backups run as part of a scheduleBasic/Standard/Advanced/Self-Hosted
security.client_cert.subject_required.enabled
booleanfalsemandates a requirement for subject role to be set for db userAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
security.ocsp.mode
enumerationoffuse OCSP to check whether TLS certificates are revoked. If the OCSP server is unreachable, in strict mode all certificates will be rejected and in lax mode all certificates will be accepted. [off = 0, lax = 1, strict = 2]Basic/Standard/Advanced/Self-Hosted
security.ocsp.timeout
duration3stimeout before considering the OCSP server unreachableBasic/Standard/Advanced/Self-Hosted
security.provisioning.ldap.enabled
booleanfalseenables automatic creation of SQL users upon successful LDAP loginBasic/Standard/Advanced/Self-Hosted
server.auth_log.sql_connections.enabled
booleanfalseif set, log SQL client connect and disconnect events to the SESSIONS log channel (note: may hinder performance on loaded nodes)Basic/Standard/Advanced/Self-Hosted
server.auth_log.sql_sessions.enabled
booleanfalseif set, log verbose SQL session authentication events to the SESSIONS log channel (note: may hinder performance on loaded nodes). Session start and end events are always logged regardless of this setting; disable the SESSIONS log channel to suppress them.Basic/Standard/Advanced/Self-Hosted
server.authentication_cache.enabled
booleantrueenables a cache used during authentication to avoid lookups to system tables when retrieving per-user authentication-related informationBasic/Standard/Advanced/Self-Hosted
server.child_metrics.enabled
booleanfalseenables the exporting of child metrics, additional prometheus time series with extra labelsBasic/Standard/Advanced/Self-Hosted
server.child_metrics.include_aggregate.enabled
booleantrueinclude the reporting of the aggregate time series when child metrics are enabled. This cluster setting has no effect if child metrics are disabled.Basic/Standard/Advanced/Self-Hosted
server.clock.forward_jump_check.enabled
(alias: server.clock.forward_jump_check_enabled)
booleanfalseif enabled, forward clock jumps > max_offset/2 will cause a panicBasic/Standard/Advanced/Self-Hosted
server.clock.persist_upper_bound_interval
duration0sthe interval between persisting the wall time upper bound of the clock. The clock does not generate a wall time greater than the persisted timestamp and will panic if it sees a wall time greater than this value. When cockroach starts, it waits for the wall time to catch-up till this persisted timestamp. This guarantees monotonic wall time across server restarts. Not setting this or setting a value of 0 disables this feature.Basic/Standard/Advanced/Self-Hosted
server.consistency_check.max_rate
byte size8.0 MiBthe rate limit (bytes/sec) to use for consistency checks; used in conjunction with server.consistency_check.interval to control the frequency of consistency checks. Note that setting this too high can negatively impact performance.Advanced/Self-Hosted
server.eventlog.enabled
booleantrueif set, logged notable events are also stored in the table system.eventlogBasic/Standard/Advanced/Self-Hosted
server.eventlog.ttl
duration2160h0m0sif nonzero, entries in system.eventlog older than this duration are periodically purgedBasic/Standard/Advanced/Self-Hosted
server.host_based_authentication.configuration
stringhost-based authentication configuration to use during connection authenticationBasic/Standard/Advanced/Self-Hosted
server.hot_ranges_request.node.timeout
duration5m0sthe duration allowed for a single node to return hot range data before the request is cancelled; if set to 0, there is no timeoutBasic/Standard/Advanced/Self-Hosted
server.hsts.enabled
booleanfalseif true, HSTS headers will be sent along with all HTTP requests. The headers will contain a max-age setting of one year. Browsers honoring the header will always use HTTPS to access the DB Console. Ensure that TLS is correctly configured prior to enabling.Basic/Standard/Advanced/Self-Hosted
server.http.base_path
string/path to redirect the user to upon succcessful loginBasic/Standard/Advanced/Self-Hosted
server.identity_map.configuration
stringsystem-identity to database-username mappingsBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.audience
stringsets accepted audience values for JWT logins over the SQL interfaceBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.claim
stringsets the JWT claim that is parsed to get the usernameBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.client.timeout
duration15ssets the client timeout for external calls made during JWT authentication (e.g. fetching JWKS, etc.)Basic/Standard/Advanced/Self-Hosted
server.jwt_authentication.enabled
booleanfalseenables or disables JWT login for the SQL interfaceBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.issuers.configuration
(alias: server.jwt_authentication.issuers)
stringsets accepted issuer values for JWT logins over the SQL interface which can be a single issuer URL string or a JSON string containing an array of issuer URLs or a JSON object containing map of issuer URLS to JWKS URIsBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.issuers.custom_ca
stringsets the PEM encoded custom root CA for verifying certificates while fetching JWKSBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.jwks
string{"keys":[]}sets the public key set for JWT logins over the SQL interface (JWKS format)Basic/Standard/Advanced/Self-Hosted
server.jwt_authentication.jwks_auto_fetch.enabled
booleanfalseenables or disables automatic fetching of JWKS from the issuer's well-known endpoint or JWKS URI set in JWTAuthIssuersConfig. If this is enabled, the server.jwt_authentication.jwks will be ignored.Basic/Standard/Advanced/Self-Hosted
server.ldap_authentication.client.tls_certificate
stringsets the client certificate PEM for establishing mTLS connection with LDAP serverBasic/Standard/Advanced/Self-Hosted
server.ldap_authentication.client.tls_key
stringsets the client key PEM for establishing mTLS connection with LDAP serverBasic/Standard/Advanced/Self-Hosted
server.ldap_authentication.domain.custom_ca
stringsets the PEM encoded custom root CA for verifying domain certificates when establishing connection with LDAP serverBasic/Standard/Advanced/Self-Hosted
server.log_gc.max_deletions_per_cycle
integer1000the maximum number of entries to delete on each purge of log-like system tablesBasic/Standard/Advanced/Self-Hosted
server.log_gc.period
duration1h0m0sthe period at which log-like system tables are checked for old entriesBasic/Standard/Advanced/Self-Hosted
server.max_connections_per_gateway
integer-1the maximum number of SQL connections per gateway allowed at a given time (note: this will only limit future connection attempts and will not affect already established connections). Negative values result in unlimited number of connections. Superusers are not affected by this limit.Basic/Standard/Advanced/Self-Hosted
server.max_open_transactions_per_gateway
integer-1the maximum number of open SQL transactions per gateway allowed at a given time. Negative values result in unlimited number of connections. Superusers are not affected by this limit.Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.autologin.enabled
(alias: server.oidc_authentication.autologin)
booleanfalseif true, logged-out visitors to the DB Console will be automatically redirected to the OIDC login endpointBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.button_text
stringLog in with your OIDC providertext to show on button on DB Console login page to login with your OIDC provider (only shown if OIDC is enabled)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.claim_json_key
stringsets JSON key of principal to extract from payload after OIDC authentication completes (usually email or sid)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.client.timeout
duration15ssets the client timeout for external calls made during OIDC authentication (e.g. authorization code flow, etc.)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.client_id
stringsets OIDC client idBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.client_secret
stringsets OIDC client secretBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.enabled
booleanfalseenables or disabled OIDC login for the DB ConsoleBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.principal_regex
string(.+)regular expression to apply to extracted principal (see claim_json_key setting) to translate to SQL user (golang regex format, must include 1 grouping to extract)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.provider.custom_ca
stringsets the PEM encoded custom root CA for verifying certificates while authenticating through the OIDC providerBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.provider_url
stringsets OIDC provider URL ({provider_url}/.well-known/openid-configuration must resolve)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.redirect_url
stringhttps://localhost:8080/oidc/v1/callbacksets OIDC redirect URL via a URL string or a JSON string containing a required `redirect_urls` key with an object that maps from region keys to URL strings (URLs should point to your load balancer and must route to the path /oidc/v1/callback)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.scopes
stringopenidsets OIDC scopes to include with authentication request (space delimited list of strings, required to start with `openid`)Basic/Standard/Advanced/Self-Hosted
server.rangelog.ttl
duration720h0m0sif nonzero, entries in system.rangelog older than this duration are periodically purgedAdvanced/Self-Hosted
server.redact_sensitive_settings.enabled
booleanfalseenables or disables the redaction of sensitive settings in the output of SHOW CLUSTER SETTINGS and SHOW ALL CLUSTER SETTINGS for users without the MODIFYCLUSTERSETTING privilegeBasic/Standard/Advanced/Self-Hosted
server.shutdown.connections.timeout
(alias: server.shutdown.connection_wait)
duration0sthe maximum amount of time a server waits for all SQL connections to be closed before proceeding with a drain. (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Basic/Standard/Advanced/Self-Hosted
server.shutdown.initial_wait
(alias: server.shutdown.drain_wait)
duration0sthe amount of time a server waits in an unready state before proceeding with a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting. --drain-wait is to specify the duration of the whole draining process, while server.shutdown.initial_wait is to set the wait time for health probes to notice that the node is not ready.)Basic/Standard/Advanced/Self-Hosted
server.shutdown.lease_transfer_iteration.timeout
(alias: server.shutdown.lease_transfer_wait)
duration5sthe timeout for a single iteration of the range lease transfer phase of draining (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Advanced/Self-Hosted
server.shutdown.transactions.timeout
(alias: server.shutdown.query_wait)
duration10sthe timeout for waiting for active transactions to finish during a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Basic/Standard/Advanced/Self-Hosted
server.sql_tcp_keep_alive.count
integer3maximum number of probes that will be sent out before a connection is dropped because it's unresponsive (Linux and Darwin only)Basic/Standard/Advanced/Self-Hosted
server.sql_tcp_keep_alive.interval
duration10stime between keep alive probes and idle time before probes are sent outBasic/Standard/Advanced/Self-Hosted
server.time_until_store_dead
duration5m0sthe time after which if there is no new gossiped information about a store, it is considered deadBasic/Standard/Advanced/Self-Hosted
server.user_login.cert_password_method.auto_scram_promotion.enabled
booleantruewhether to automatically promote cert-password authentication to use SCRAMBasic/Standard/Advanced/Self-Hosted
server.user_login.downgrade_scram_stored_passwords_to_bcrypt.enabled
booleantrueif server.user_login.password_encryption=crdb-bcrypt, this controls whether to automatically re-encode stored passwords using scram-sha-256 to crdb-bcryptBasic/Standard/Advanced/Self-Hosted
server.user_login.min_password_length
integer1the minimum length accepted for passwords set in cleartext via SQL. Note that a value lower than 1 is ignored: passwords cannot be empty in any case. This setting only applies when adding new users or altering an existing user's password; it will not affect existing logins.Basic/Standard/Advanced/Self-Hosted
server.user_login.password_encryption
enumerationscram-sha-256which hash method to use to encode cleartext passwords passed via ALTER/CREATE USER/ROLE WITH PASSWORD [crdb-bcrypt = 2, scram-sha-256 = 3]Basic/Standard/Advanced/Self-Hosted
server.user_login.password_hashes.default_cost.crdb_bcrypt
integer10the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method crdb-bcrypt (allowed range: 4-31)Basic/Standard/Advanced/Self-Hosted
server.user_login.password_hashes.default_cost.scram_sha_256
integer10610the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method scram-sha-256 (allowed range: 4096-240000000000)Basic/Standard/Advanced/Self-Hosted
server.user_login.rehash_scram_stored_passwords_on_cost_change.enabled
booleantrueif server.user_login.password_hashes.default_cost.scram_sha_256 differs from, the cost in a stored hash, this controls whether to automatically re-encode stored passwords using scram-sha-256 with the new default costBasic/Standard/Advanced/Self-Hosted
server.user_login.timeout
duration10stimeout after which client authentication times out if some system range is unavailable (0 = no timeout)Basic/Standard/Advanced/Self-Hosted
server.user_login.upgrade_bcrypt_stored_passwords_to_scram.enabled
booleantrueif server.user_login.password_encryption=scram-sha-256, this controls whether to automatically re-encode stored passwords using crdb-bcrypt to scram-sha-256Basic/Standard/Advanced/Self-Hosted
server.web_session.purge.ttl
duration1h0m0sif nonzero, entries in system.web_sessions older than this duration are periodically purgedBasic/Standard/Advanced/Self-Hosted
server.web_session.timeout
(alias: server.web_session_timeout)
duration168h0m0sthe duration that a newly created web session will be validBasic/Standard/Advanced/Self-Hosted
spanconfig.bounds.enabled
booleantruedictates whether span config bounds are consulted when serving span configs for secondary tenantsAdvanced/Self-Hosted
spanconfig.range_coalescing.system.enabled
(alias: spanconfig.storage_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs, for the ranges specific to the system tenantAdvanced/Self-Hosted
spanconfig.range_coalescing.application.enabled
(alias: spanconfig.tenant_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs across all secondary tenant keyspacesAdvanced/Self-Hosted
sql.auth.change_own_password.enabled
booleanfalsecontrols whether a user is allowed to change their own password, even if they have no other privilegesBasic/Standard/Advanced/Self-Hosted
sql.auth.grant_option_for_owner.enabled
booleantruedetermines whether the GRANT OPTION for privileges is implicitly given to the owner of an objectBasic/Standard/Advanced/Self-Hosted
sql.auth.grant_option_inheritance.enabled
booleantruedetermines whether the GRANT OPTION for privileges is inherited through role membershipBasic/Standard/Advanced/Self-Hosted
sql.auth.public_schema_create_privilege.enabled
booleantruedetermines whether to grant all users the CREATE privileges on the public schema when it is createdBasic/Standard/Advanced/Self-Hosted
sql.closed_session_cache.capacity
integer1000the maximum number of sessions in the cacheBasic/Standard/Advanced/Self-Hosted
sql.closed_session_cache.time_to_live
integer3600the maximum time to live, in secondsBasic/Standard/Advanced/Self-Hosted
sql.contention.event_store.capacity
byte size64 MiBthe in-memory storage capacity per-node of contention event storeBasic/Standard/Advanced/Self-Hosted
sql.contention.event_store.duration_threshold
duration0sminimum contention duration to cause the contention events to be collected into crdb_internal.transaction_contention_eventsBasic/Standard/Advanced/Self-Hosted
sql.contention.record_serialization_conflicts.enabled
booleantrueenables recording 40001 errors with conflicting txn meta as SERIALIZATION_CONFLICTcontention events into crdb_internal.transaction_contention_eventsBasic/Standard/Advanced/Self-Hosted
sql.contention.txn_id_cache.max_size
byte size64 MiBthe maximum byte size TxnID cache will use (set to 0 to disable)Basic/Standard/Advanced/Self-Hosted
sql.cross_db_fks.enabled
booleanfalseif true, creating foreign key references across databases is allowedBasic/Standard/Advanced/Self-Hosted
sql.cross_db_sequence_owners.enabled
booleanfalseif true, creating sequences owned by tables from other databases is allowedBasic/Standard/Advanced/Self-Hosted
sql.cross_db_sequence_references.enabled
booleanfalseif true, sequences referenced by tables from other databases are allowedBasic/Standard/Advanced/Self-Hosted
sql.cross_db_views.enabled
booleanfalseif true, creating views that refer to other databases is allowedBasic/Standard/Advanced/Self-Hosted
sql.defaults.cost_scans_with_default_col_size.enabled
booleanfalsesetting to true uses the same size for all columns to compute scan cost
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.datestyle
enumerationiso, mdydefault value for DateStyle session setting [iso, mdy = 0, iso, dmy = 1, iso, ymd = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.default_hash_sharded_index_bucket_count
integer16used as bucket count if bucket count is not specified in hash sharded index definition
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.default_int_size
integer8the size, in bytes, of an INT type
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.disallow_full_table_scans.enabled
booleanfalsesetting to true rejects queries that have planned a full table scan; set large_full_scan_rows > 0 to allow small full table scans estimated to read fewer than large_full_scan_rows
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.distsql
enumerationautodefault distributed SQL execution mode [off = 0, auto = 1, on = 2, always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_alter_column_type.enabled
booleanfalsedefault value for experimental_alter_column_type session setting; enables the use of ALTER COLUMN TYPE for general conversions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_distsql_planning
enumerationoffdefault experimental_distsql_planning mode; enables experimental opt-driven DistSQL planning [off = 0, on = 1]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_enable_unique_without_index_constraints.enabled
booleanfalsedefault value for experimental_enable_unique_without_index_constraints session setting;disables unique without index constraints by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_implicit_column_partitioning.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for the use of implicit column partitioning
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_temporary_tables.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for use of temporary tables by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.foreign_key_cascades_limit
integer10000default value for foreign_key_cascades_limit session setting; limits the number of cascading operations that run as part of a single query
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.idle_in_session_timeout
duration0sdefault value for the idle_in_session_timeout; default value for the idle_in_session_timeout session setting; controls the duration a session is permitted to idle before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.idle_in_transaction_session_timeout
duration0sdefault value for the idle_in_transaction_session_timeout; controls the duration a session is permitted to idle in a transaction before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.implicit_select_for_update.enabled
booleantruedefault value for enable_implicit_select_for_update session setting; enables FOR UPDATE locking during the row-fetch phase of mutation statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.insert_fast_path.enabled
booleantruedefault value for enable_insert_fast_path session setting; enables a specialized insert path
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.intervalstyle
enumerationpostgresdefault value for IntervalStyle session setting [postgres = 0, iso_8601 = 1, sql_standard = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.large_full_scan_rows
float0default value for large_full_scan_rows session variable which determines the table size at which full scans are considered large and disallowed when disallow_full_table_scans is set to true; set to 0 to reject all full table or full index scans when disallow_full_table_scans is true
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.locality_optimized_partitioned_index_scan.enabled
booleantruedefault value for locality_optimized_partitioned_index_scan session setting; enables searching for rows in the current region before searching remote regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.lock_timeout
duration0sdefault value for the lock_timeout; default value for the lock_timeout session setting; controls the duration a query is permitted to wait while attempting to acquire a lock on a key or while blocking on an existing lock in order to perform a non-locking read on a key; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.on_update_rehome_row.enabled
booleantruedefault value for on_update_rehome_row; enables ON UPDATE rehome_row() expressions to trigger on updates
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.optimizer_use_histograms.enabled
booleantruedefault value for optimizer_use_histograms session setting; enables usage of histograms in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.optimizer_use_multicol_stats.enabled
booleantruedefault value for optimizer_use_multicol_stats session setting; enables usage of multi-column stats in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.override_alter_primary_region_in_super_region.enabled
booleanfalsedefault value for override_alter_primary_region_in_super_region; allows for altering the primary region even if the primary region is a member of a super region
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.override_multi_region_zone_config.enabled
booleanfalsedefault value for override_multi_region_zone_config; allows for overriding the zone configs of a multi-region table or database
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.prefer_lookup_joins_for_fks.enabled
booleanfalsedefault value for prefer_lookup_joins_for_fks session setting; causes foreign key operations to use lookup joins when possible
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.primary_region
stringif not empty, all databases created without a PRIMARY REGION will implicitly have the given PRIMARY REGION
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.reorder_joins_limit
integer8default number of joins to reorder
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.require_explicit_primary_keys.enabled
booleanfalsedefault value for requiring explicit primary keys in CREATE TABLE statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.results_buffer.size
byte size512 KiBdefault size of the buffer that accumulates results for a statement or a batch of statements before they are sent to the client. This can be overridden on an individual connection with the 'results_buffer_size' parameter. Note that auto-retries generally only happen while no results have been delivered to the client, so reducing this size can increase the number of retriable errors a client receives. On the other hand, increasing the buffer size can increase the delay until the client receives the first result row. Updating the setting only affects new connections. Setting to 0 disables any buffering.
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.serial_normalization
enumerationrowiddefault handling of SERIAL in table definitions [rowid = 0, virtual_sequence = 1, sql_sequence = 2, sql_sequence_cached = 3, unordered_rowid = 4, sql_sequence_cached_node = 5]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.statement_timeout
duration0sdefault value for the statement_timeout; default value for the statement_timeout session setting; controls the duration a query is permitted to run before it is canceled; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.stub_catalog_tables.enabled
booleantruedefault value for stub_catalog_tables session setting
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.super_regions.enabled
booleanfalsedefault value for enable_super_regions; allows for the usage of super regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.transaction_rows_read_err
integer0the limit for the number of rows read by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.transaction_rows_read_log
integer0the threshold for the number of rows read by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.transaction_rows_written_err
integer0the limit for the number of rows written by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.transaction_rows_written_log
integer0the threshold for the number of rows written by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.use_declarative_schema_changer
enumerationondefault value for use_declarative_schema_changer session setting;disables new schema changer by default [off = 0, on = 1, unsafe = 2, unsafe_always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.vectorize
enumerationondefault vectorize mode [on = 0, on = 1, on = 2, experimental_always = 3, off = 4]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.zigzag_join.enabled
booleanfalsedefault value for enable_zigzag_join session setting; disallows use of zig-zag join by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.distsql.temp_storage.workmem
byte size64 MiBmaximum amount of memory in bytes a processor can use before falling back to temp storageBasic/Standard/Advanced/Self-Hosted
sql.guardrails.max_row_size_err
byte size512 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an error is returned; use 0 to disableBasic/Standard/Advanced/Self-Hosted
sql.guardrails.max_row_size_log
byte size64 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an event is logged to SQL_PERF (or SQL_INTERNAL_PERF if the mutating statement was internal); use 0 to disableBasic/Standard/Advanced/Self-Hosted
sql.hash_sharded_range_pre_split.max
integer16max pre-split ranges to have when adding hash sharded index to an existing tableBasic/Standard/Advanced/Self-Hosted
sql.index_recommendation.drop_unused_duration
duration168h0m0sthe index unused duration at which we begin to recommend dropping the indexBasic/Standard/Advanced/Self-Hosted
sql.insights.anomaly_detection.enabled
booleantrueenable per-fingerprint latency recording and anomaly detectionBasic/Standard/Advanced/Self-Hosted
sql.insights.anomaly_detection.latency_threshold
duration50msstatements must surpass this threshold to trigger anomaly detection and identificationBasic/Standard/Advanced/Self-Hosted
sql.insights.anomaly_detection.memory_limit
byte size1.0 MiBthe maximum amount of memory allowed for tracking statement latenciesBasic/Standard/Advanced/Self-Hosted
sql.insights.execution_insights_capacity
integer1000the size of the per-node store of execution insightsBasic/Standard/Advanced/Self-Hosted
sql.insights.high_retry_count.threshold
integer10the number of retries a slow statement must have undergone for its high retry count to be highlighted as a potential problemBasic/Standard/Advanced/Self-Hosted
sql.insights.latency_threshold
duration100msamount of time after which an executing statement is considered slow. Use 0 to disable.Basic/Standard/Advanced/Self-Hosted
sql.log.redact_names.enabled
booleanfalseif set, schema object identifers are redacted in SQL statements that appear in event logsBasic/Standard/Advanced/Self-Hosted
sql.log.slow_query.experimental_full_table_scans.enabled
booleanfalsewhen set to true, statements that perform a full table/index scan will be logged to the slow query log even if they do not meet the latency threshold. Must have the slow query log enabled for this setting to have any effect.Basic/Standard/Advanced/Self-Hosted
sql.log.slow_query.internal_queries.enabled
booleanfalsewhen set to true, internal queries which exceed the slow query log threshold are logged to a separate log. Must have the slow query log enabled for this setting to have any effect.Basic/Standard/Advanced/Self-Hosted
sql.log.slow_query.latency_threshold
duration0swhen set to non-zero, log statements whose service latency exceeds the threshold to a secondary logger on each nodeBasic/Standard/Advanced/Self-Hosted
sql.log.user_audit
stringuser/role-based audit logging configuration. An enterprise license is required for this cluster setting to take effect.Basic/Standard/Advanced/Self-Hosted
sql.log.user_audit.reduced_config.enabled
booleanfalseenables logic to compute a reduced audit configuration, computing the audit configuration only once at session start instead of at each SQL event. The tradeoff with the increase in performance (~5%), is that changes to the audit configuration (user role memberships/cluster setting) are not reflected within session. Users will need to start a new session to see these changes in their auditing behaviour.Basic/Standard/Advanced/Self-Hosted
sql.metrics.application_name.enabled
booleanfalsewhen enabled, SQL metrics would export application name as and additional label as part of child metrics. The number of unique label combinations is limited to 5000 by default.Basic/Standard/Advanced/Self-Hosted
sql.metrics.database_name.enabled
booleanfalsewhen enabled, SQL metrics would export database name as and additional label as part of child metrics. The number of unique label combinations is limited to 5000 by default.Basic/Standard/Advanced/Self-Hosted
sql.metrics.index_usage_stats.enabled
booleantruecollect per index usage statisticsBasic/Standard/Advanced/Self-Hosted
sql.metrics.max_mem_reported_stmt_fingerprints
integer100000the maximum number of reported statement fingerprints stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.max_mem_reported_txn_fingerprints
integer100000the maximum number of reported transaction fingerprints stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.max_mem_stmt_fingerprints
integer7500the maximum number of statement fingerprints stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.max_mem_txn_fingerprints
integer7500the maximum number of transaction fingerprints stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.dump_to_logs.enabled
(alias: sql.metrics.statement_details.dump_to_logs)
booleanfalsedump collected statement statistics to node logs when periodically clearedBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.enabled
booleantruecollect per-statement query statisticsBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.gateway_node.enabled
booleanfalsesave the gateway node for each statement fingerprint. If false, the value will be stored as 0.Basic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.index_recommendation_collection.enabled
booleantruegenerate an index recommendation for each fingerprint IDBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.max_mem_reported_idx_recommendations
integer5000the maximum number of reported index recommendation info stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.threshold
duration0sminimum execution time to cause statement statistics to be collected. If configured, no transaction stats are collected.Basic/Standard/Advanced/Self-Hosted
sql.metrics.transaction_details.enabled
booleantruecollect per-application transaction statisticsBasic/Standard/Advanced/Self-Hosted
sql.multiple_modifications_of_table.enabled
booleanfalseif true, allow statements containing multiple INSERT ON CONFLICT, UPSERT, UPDATE, or DELETE subqueries modifying the same table, at the risk of data corruption if the same row is modified multiple times by a single statement (multiple INSERT subqueries without ON CONFLICT cannot cause corruption and are always allowed)Basic/Standard/Advanced/Self-Hosted
sql.multiregion.drop_primary_region.enabled
booleantrueallows dropping the PRIMARY REGION of a database if it is the last regionBasic/Standard/Advanced/Self-Hosted
sql.notices.enabled
booleantrueenable notices in the server/client protocol being sentBasic/Standard/Advanced/Self-Hosted
sql.optimizer.uniqueness_checks_for_gen_random_uuid.enabled
booleanfalseif enabled, uniqueness checks may be planned for mutations of UUID columns updated with gen_random_uuid(); otherwise, uniqueness is assumed due to near-zero collision probabilityBasic/Standard/Advanced/Self-Hosted
sql.schema.telemetry.recurrence
string@weeklycron-tab recurrence for SQL schema telemetry jobAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
sql.spatial.experimental_box2d_comparison_operators.enabled
booleanfalseenables the use of certain experimental box2d comparison operatorsBasic/Standard/Advanced/Self-Hosted
sql.sqlcommenter.enabled
booleanfalseenables support for sqlcommenter. Key value parsed from sqlcommenter comments will be included in sql insights and sql logs. See https://google.github.io/sqlcommenter/ for more details.Basic/Standard/Advanced/Self-Hosted
sql.stats.activity.persisted_rows.max
integer200000maximum number of rows of statement and transaction activity that will be persisted in the system tablesBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_collection.enabled
booleantrueautomatic statistics collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_collection.fraction_stale_rows
float0.2target fraction of stale rows per table that will trigger a statistics refreshBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_collection.min_stale_rows
integer500target minimum number of stale rows per table that will trigger a statistics refreshBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_full_collection.enabled
booleantrueautomatic full statistics collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_partial_collection.enabled
booleantrueautomatic partial statistics collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_partial_collection.fraction_stale_rows
float0.05target fraction of stale rows per table that will trigger a partial statistics refreshBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_partial_collection.min_stale_rows
integer100target minimum number of stale rows per table that will trigger a partial statistics refreshBasic/Standard/Advanced/Self-Hosted
sql.stats.cleanup.recurrence
string@hourlycron-tab recurrence for SQL Stats cleanup jobBasic/Standard/Advanced/Self-Hosted
sql.stats.detailed_latency_metrics.enabled
booleanfalselabel latency metrics with the statement fingerprint. Workloads with tens of thousands of distinct query fingerprints should leave this setting false. (experimental, affects performance for workloads with high fingerprint cardinality)Basic/Standard/Advanced/Self-Hosted
sql.stats.error_on_concurrent_create_stats.enabled
booleanfalseset to true to error on concurrent CREATE STATISTICS jobs, instead of skipping themBasic/Standard/Advanced/Self-Hosted
sql.stats.flush.enabled
booleantrueif set, SQL execution statistics are periodically flushed to diskBasic/Standard/Advanced/Self-Hosted
sql.stats.flush.interval
duration10m0sthe interval at which SQL execution statistics are flushed to disk, this value must be less than or equal to 1 hourBasic/Standard/Advanced/Self-Hosted
sql.stats.forecasts.enabled
booleantruewhen true, enables generation of statistics forecasts by default for all tablesBasic/Standard/Advanced/Self-Hosted
sql.stats.forecasts.max_decrease
float0.3333333333333333the most a prediction is allowed to decrease, expressed as the minimum ratio of the prediction to the lowest prior observationBasic/Standard/Advanced/Self-Hosted
sql.stats.forecasts.min_goodness_of_fit
float0.95the minimum R² (goodness of fit) measurement required from all predictive models to use a forecastBasic/Standard/Advanced/Self-Hosted
sql.stats.forecasts.min_observations
integer3the mimimum number of observed statistics required to produce a statistics forecastBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_buckets.count
integer200maximum number of histogram buckets to build during table statistics collectionBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_buckets.include_most_common_values.enabled
booleantruewhether to include most common values as histogram bucketsBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_buckets.max_fraction_most_common_values
float0.1maximum fraction of histogram buckets to use for most common valuesBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_collection.enabled
booleantruehistogram collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_samples.count
integer0number of rows sampled for histogram construction during table statistics collection. Not setting this or setting a value of 0 means that a reasonable sample size will be automatically picked based on the table size.Basic/Standard/Advanced/Self-Hosted
sql.stats.multi_column_collection.enabled
booleantruemulti-column statistics collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.non_default_columns.min_retention_period
duration24h0m0sminimum retention period for table statistics collected on non-default columnsBasic/Standard/Advanced/Self-Hosted
sql.stats.non_indexed_json_histograms.enabled
booleanfalseset to true to collect table statistics histograms on non-indexed JSON columnsBasic/Standard/Advanced/Self-Hosted
sql.stats.persisted_rows.max
integer1000000maximum number of rows of statement and transaction statistics that will be persisted in the system tables before compaction beginsBasic/Standard/Advanced/Self-Hosted
sql.stats.post_events.enabled
booleanfalseif set, an event is logged for every successful CREATE STATISTICS jobBasic/Standard/Advanced/Self-Hosted
sql.stats.response.max
integer20000the maximum number of statements and transaction stats returned in a CombinedStatements requestBasic/Standard/Advanced/Self-Hosted
sql.stats.response.show_internal.enabled
booleanfalsecontrols if statistics for internal executions should be returned by the CombinedStatements and if internal sessions should be returned by the ListSessions endpoints. These endpoints are used to display statistics on the SQL Activity pagesBasic/Standard/Advanced/Self-Hosted
sql.stats.system_tables.enabled
booleantruewhen true, enables use of statistics on system tables by the query optimizerBasic/Standard/Advanced/Self-Hosted
sql.stats.system_tables_autostats.enabled
booleantruewhen true, enables automatic collection of statistics on system tablesBasic/Standard/Advanced/Self-Hosted
sql.stats.virtual_computed_columns.enabled
booleantrueset to true to collect table statistics on virtual computed columnsBasic/Standard/Advanced/Self-Hosted
sql.telemetry.query_sampling.enabled
booleanfalsewhen set to true, executed queries will emit an event on the telemetry logging channelBasic/Standard/Advanced/Self-Hosted
sql.telemetry.query_sampling.internal.enabled
booleanfalsewhen set to true, internal queries will be sampled in telemetry loggingBasic/Standard/Advanced/Self-Hosted
sql.telemetry.query_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample executions for telemetry, note that it is recommended that this value shares a log-line limit of 10 logs per second on the telemetry pipeline with all other telemetry events. If sampling mode is set to 'transaction', this value is ignored.Basic/Standard/Advanced/Self-Hosted
sql.telemetry.query_sampling.mode
enumerationstatementthe execution level used for telemetry sampling. If set to 'statement', events are sampled at the statement execution level. If set to 'transaction', events are sampled at the transaction execution level, i.e. all statements for a transaction will be logged and are counted together as one sampled event (events are still emitted one per statement). [statement = 0, transaction = 1]Basic/Standard/Advanced/Self-Hosted
sql.telemetry.transaction_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample transactions for telemetry. If sampling mode is set to 'statement', this setting is ignored. In practice, this means that we only sample a transaction if 1/max_event_frequency seconds have elapsed since the last transaction was sampled.Basic/Standard/Advanced/Self-Hosted
sql.telemetry.transaction_sampling.statement_events_per_transaction.max
integer50the maximum number of statement events to log for every sampled transaction. Note that statements that are logged by force do not adhere to this limit.Basic/Standard/Advanced/Self-Hosted
sql.temp_object_cleaner.cleanup_interval
duration30m0show often to clean up orphaned temporary objectsBasic/Standard/Advanced/Self-Hosted
sql.temp_object_cleaner.wait_interval
duration30m0show long after creation a temporary object will be cleaned upBasic/Standard/Advanced/Self-Hosted
sql.log.all_statements.enabled
(alias: sql.trace.log_statement_execute)
booleanfalseset to true to enable logging of all executed statementsBasic/Standard/Advanced/Self-Hosted
sql.trace.stmt.enable_threshold
duration0senables tracing on all statements; statements executing for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting applies to individual statements within a transaction and is therefore finer-grained than sql.trace.txn.enable_thresholdBasic/Standard/Advanced/Self-Hosted
sql.trace.txn.enable_threshold
duration0senables transaction traces for transactions exceeding this duration, used with `sql.trace.txn.sample_rate`Basic/Standard/Advanced/Self-Hosted
sql.trace.txn.sample_rate
float1enables probabilistic transaction tracing. It should be used in conjunction with `sql.trace.txn.enable_threshold`. A percentage of transactions between 0 and 1.0 will have tracing enabled, and only those which exceed the configured threshold will be logged.Basic/Standard/Advanced/Self-Hosted
sql.ttl.changefeed_replication.disabled
booleanfalseif true, deletes issued by TTL will not be replicated via changefeeds (this setting will be ignored by changefeeds that have the ignore_disable_changefeed_replication option set; such changefeeds will continue to replicate all TTL deletes)Basic/Standard/Advanced/Self-Hosted
sql.ttl.default_delete_batch_size
integer100default amount of rows to delete in a single query during a TTL jobBasic/Standard/Advanced/Self-Hosted
sql.ttl.default_delete_rate_limit
integer100default delete rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Basic/Standard/Advanced/Self-Hosted
sql.ttl.default_select_batch_size
integer500default amount of rows to select in a single query during a TTL jobBasic/Standard/Advanced/Self-Hosted
sql.ttl.default_select_rate_limit
integer0default select rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Basic/Standard/Advanced/Self-Hosted
sql.ttl.job.enabled
booleantruewhether the TTL job is enabledBasic/Standard/Advanced/Self-Hosted
sql.txn.read_committed_isolation.enabled
booleantrueset to true to allow transactions to use the READ COMMITTED isolation level if specified by BEGIN/SET commandsBasic/Standard/Advanced/Self-Hosted
sql.txn.repeatable_read_isolation.enabled
(alias: sql.txn.snapshot_isolation.enabled)
booleanfalseset to true to allow transactions to use the REPEATABLE READ isolation level if specified by BEGIN/SET commandsBasic/Standard/Advanced/Self-Hosted
sql.txn_fingerprint_id_cache.capacity
integer100the maximum number of txn fingerprint IDs storedBasic/Standard/Advanced/Self-Hosted
sql.vecindex.stalled_op.timeout
duration100msamount of time before other vector index workers will assist with a stalled background fixupBasic/Standard/Advanced/Self-Hosted
storage.columnar_blocks.enabled
booleantrueset to true to enable columnar-blocks to store KVs in a columnar formatAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.delete_compaction_excise.enabled
booleantrueset to false to direct Pebble to not partially excise sstables in delete-only compactionsAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.ingest_split.enabled
booleantrueset to false to disable ingest-time splitting that lowers write-amplificationAdvanced/Self-Hosted
storage.ingestion.value_blocks.enabled
booleantrueset to true to enable writing of value blocks in ingestion sstablesBasic/Standard/Advanced/Self-Hosted
storage.max_sync_duration
duration20smaximum duration for disk operations; any operations that take longer than this setting trigger a warning log entry or process crashAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.max_sync_duration.fatal.enabled
booleantrueif true, fatal the process when a disk operation exceeds storage.max_sync_durationBasic/Standard/Advanced/Self-Hosted
storage.sstable.compression_algorithm
enumerationfastestdetermines the compression algorithm to use when compressing sstable data blocks for use in a Pebble store (balanced,good are experimental); [snappy = 1, zstd = 2, none = 3, minlz = 4, fastest = 5, balanced = 6, good = 7]Advanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.sstable.compression_algorithm_backup_storage
enumerationfastestdetermines the compression algorithm to use when compressing sstable data blocks for backup row data storage (fast,balanced,good are experimental); [snappy = 1, zstd = 2, none = 3, minlz = 4, fastest = 5, fast = 6, balanced = 7, good = 8]Advanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.sstable.compression_algorithm_backup_transport
enumerationfastestdetermines the compression algorithm to use when compressing sstable data blocks for backup transport (fast,balanced,good are experimental); [snappy = 1, zstd = 2, none = 3, minlz = 4, fastest = 5, fast = 6, balanced = 7, good = 8]Advanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.wal_failover.unhealthy_op_threshold
duration100msthe latency of a WAL write considered unhealthy and triggers a failover to a secondary WAL locationAdvanced/Self-Hosted
timeseries.storage.enabled
booleantrueif set, periodic timeseries data is stored within the cluster; disabling is not recommended unless you are storing the data elsewhereAdvanced/Self-Hosted
timeseries.storage.resolution_10s.ttl
duration240h0m0sthe maximum age of time series data stored at the 10 second resolution. Data older than this is subject to rollup and deletion.Advanced/Self-hosted (read-write); Basic/Standard (read-only)
timeseries.storage.resolution_30m.ttl
duration2160h0m0sthe maximum age of time series data stored at the 30 minute resolution. Data older than this is subject to deletion.Advanced/Self-hosted (read-write); Basic/Standard (read-only)
trace.debug_http_endpoint.enabled
(alias: trace.debug.enable)
booleanfalseif set, traces for recent requests can be seen at https://<ui>/debug/requestsBasic/Standard/Advanced/Self-Hosted
trace.opentelemetry.collector
stringaddress of an OpenTelemetry trace collector to receive traces using the otel gRPC protocol, as <host>:<port>. If no port is specified, 4317 will be used.Basic/Standard/Advanced/Self-Hosted
trace.snapshot.rate
duration0sif non-zero, interval at which background trace snapshots are capturedBasic/Standard/Advanced/Self-Hosted
trace.span_registry.enabled
booleanfalseif set, ongoing traces can be seen at https://<ui>/#/debug/tracezBasic/Standard/Advanced/Self-Hosted
trace.zipkin.collector
stringthe address of a Zipkin instance to receive traces, as <host>:<port>. If no port is specified, 9411 will be used.Basic/Standard/Advanced/Self-Hosted
ui.database_locality_metadata.enabled
booleantrueif enabled shows extended locality data about databases and tables in DB Console which can be expensive to computeBasic/Standard/Advanced/Self-Hosted
ui.default_timezone
stringthe default timezone used to format timestamps in the uiBasic/Standard/Advanced/Self-Hosted
ui.display_timezone
enumerationetc/utcthe timezone used to format timestamps in the ui. This setting is deprecatedand will be removed in a future version. Use the 'ui.default_timezone' setting instead. 'ui.default_timezone' takes precedence over this setting. [etc/utc = 0, america/new_york = 1]Basic/Standard/Advanced/Self-Hosted
version
version25.3set the active cluster version in the format '<major>.<minor>'Basic/Standard/Advanced/Self-Hosted
diff --git a/src/current/_includes/cockroach-generated/release-25.3/sql/aggregates.md b/src/current/_includes/cockroach-generated/release-25.3/sql/aggregates.md new file mode 100644 index 00000000000..3213f0f02a8 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.3/sql/aggregates.md @@ -0,0 +1,579 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_agg(arg1: bool) → bool[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bool[]) → bool[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes) → bytes[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes[]) → bytes[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date) → date[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date[]) → date[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal) → decimal[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal[]) → decimal[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float) → float[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float[]) → float[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet) → inet[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet[]) → inet[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int) → int[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int[]) → int[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval) → interval[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval[]) → interval[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string) → string[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string[]) → string[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time) → time[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time[]) → time[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp) → timestamp[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp[]) → timestamp[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz) → timestamptz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz[]) → timestamptz[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid) → uuid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid[]) → uuid[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum) → anyenum[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum[]) → anyenum[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d) → box2d[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d[]) → box2d[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography) → geography[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography[]) → geography[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry) → geometry[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry[]) → geometry[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb) → jsonb[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb[]) → jsonb[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid) → oid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid[]) → oid[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn) → pg_lsn[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn[]) → pg_lsn[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor) → refcursor[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor[]) → refcursor[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz) → timetz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz[]) → timetz[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple) → tuple[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple[]) → tuple[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit) → varbit[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit[]) → varbit[][]

Aggregates the selected values into an array.

+		Immutable
array_cat_agg(arg1: bool[]) → bool[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: bytes[]) → bytes[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: date[]) → date[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: decimal[]) → decimal[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: float[]) → float[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: inet[]) → inet[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: int[]) → int[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: interval[]) → interval[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: string[]) → string[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: time[]) → time[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamp[]) → timestamp[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamptz[]) → timestamptz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: uuid[]) → uuid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: anyenum[]) → anyenum[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: box2d[]) → box2d[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geography[]) → geography[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geometry[]) → geometry[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: jsonb[]) → jsonb[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: oid[]) → oid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: pg_lsn[]) → pg_lsn[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: refcursor[]) → refcursor[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timetz[]) → timetz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: tuple[]) → tuple[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: varbit[]) → varbit[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
avg(arg1: decimal) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: float) → float

Calculates the average of the selected values.

+		Immutable
avg(arg1: int) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: interval) → interval

Calculates the average of the selected values.

+		Immutable
bit_and(arg1: int) → int

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_and(arg1: varbit) → varbit

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: int) → int

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: varbit) → varbit

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bool_and(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
bool_or(arg1: bool) → bool

Calculates the boolean value of ORing all selected values.

+		Immutable
concat_agg(arg1: bytes) → bytes

Concatenates all selected values.

+		Immutable
concat_agg(arg1: string) → string

Concatenates all selected values.

+		Immutable
corr(arg1: decimal, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
count(arg1: anyelement) → int

Calculates the number of selected elements.

+		Immutable
count_rows() → int

Calculates the number of rows.

+		Immutable
covar_pop(arg1: decimal, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
every(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
json_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
json_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
jsonb_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
jsonb_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
max(arg1: bool) → bool

Identifies the maximum selected value.

+		Immutable
max(arg1: bytes) → bytes

Identifies the maximum selected value.

+		Immutable
max(arg1: date) → date

Identifies the maximum selected value.

+		Immutable
max(arg1: decimal) → decimal

Identifies the maximum selected value.

+		Immutable
max(arg1: float) → float

Identifies the maximum selected value.

+		Immutable
max(arg1: inet) → inet

Identifies the maximum selected value.

+		Immutable
max(arg1: int) → int

Identifies the maximum selected value.

+		Immutable
max(arg1: interval) → interval

Identifies the maximum selected value.

+		Immutable
max(arg1: string) → string

Identifies the maximum selected value.

+		Immutable
max(arg1: time) → time

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamp) → timestamp

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamptz) → timestamptz

Identifies the maximum selected value.

+		Immutable
max(arg1: uuid) → uuid

Identifies the maximum selected value.

+		Immutable
max(arg1: anyenum) → anyenum

Identifies the maximum selected value.

+		Immutable
max(arg1: box2d) → box2d

Identifies the maximum selected value.

+		Immutable
max(arg1: collatedstring{*}) → collatedstring{*}

Identifies the maximum selected value.

+		Immutable
max(arg1: geography) → geography

Identifies the maximum selected value.

+		Immutable
max(arg1: geometry) → geometry

Identifies the maximum selected value.

+		Immutable
max(arg1: jsonb) → jsonb

Identifies the maximum selected value.

+		Immutable
max(arg1: oid) → oid

Identifies the maximum selected value.

+		Immutable
max(arg1: pg_lsn) → pg_lsn

Identifies the maximum selected value.

+		Immutable
max(arg1: timetz) → timetz

Identifies the maximum selected value.

+		Immutable
max(arg1: varbit) → varbit

Identifies the maximum selected value.

+		Immutable
min(arg1: bool) → bool

Identifies the minimum selected value.

+		Immutable
min(arg1: bytes) → bytes

Identifies the minimum selected value.

+		Immutable
min(arg1: date) → date

Identifies the minimum selected value.

+		Immutable
min(arg1: decimal) → decimal

Identifies the minimum selected value.

+		Immutable
min(arg1: float) → float

Identifies the minimum selected value.

+		Immutable
min(arg1: inet) → inet

Identifies the minimum selected value.

+		Immutable
min(arg1: int) → int

Identifies the minimum selected value.

+		Immutable
min(arg1: interval) → interval

Identifies the minimum selected value.

+		Immutable
min(arg1: string) → string

Identifies the minimum selected value.

+		Immutable
min(arg1: time) → time

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamp) → timestamp

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamptz) → timestamptz

Identifies the minimum selected value.

+		Immutable
min(arg1: uuid) → uuid

Identifies the minimum selected value.

+		Immutable
min(arg1: anyenum) → anyenum

Identifies the minimum selected value.

+		Immutable
min(arg1: box2d) → box2d

Identifies the minimum selected value.

+		Immutable
min(arg1: collatedstring{*}) → collatedstring{*}

Identifies the minimum selected value.

+		Immutable
min(arg1: geography) → geography

Identifies the minimum selected value.

+		Immutable
min(arg1: geometry) → geometry

Identifies the minimum selected value.

+		Immutable
min(arg1: jsonb) → jsonb

Identifies the minimum selected value.

+		Immutable
min(arg1: oid) → oid

Identifies the minimum selected value.

+		Immutable
min(arg1: pg_lsn) → pg_lsn

Identifies the minimum selected value.

+		Immutable
min(arg1: timetz) → timetz

Identifies the minimum selected value.

+		Immutable
min(arg1: varbit) → varbit

Identifies the minimum selected value.

+		Immutable
percentile_cont(arg1: float) → float

Continuous percentile: returns a float corresponding to the specified fraction in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float) → interval

Continuous percentile: returns an interval corresponding to the specified fraction in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_cont(arg1: float[]) → float[]

Continuous percentile: returns floats corresponding to the specified fractions in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float[]) → interval[]

Continuous percentile: returns intervals corresponding to the specified fractions in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_disc(arg1: float) → anyelement

Discrete percentile: returns the first input value whose position in the ordering equals or exceeds the specified fraction.

+		Immutable
percentile_disc(arg1: float[]) → anyelement

Discrete percentile: returns input values whose position in the ordering equals or exceeds the specified fractions.

+		Immutable
regr_avgx(arg1: decimal, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_count(arg1: decimal, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_intercept(arg1: decimal, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_r2(arg1: decimal, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_slope(arg1: decimal, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_sxx(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
sqrdiff(arg1: decimal) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: float) → float

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: int) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
st_collect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_extent(arg1: geometry) → box2d

Forms a Box2D that encapsulates all provided geometries.

+		Immutable
st_makeline(arg1: geometry) → geometry

Forms a LineString from Point, MultiPoint or LineStrings. Other shapes will be ignored.

+		Immutable
st_memcollect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_memunion(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
st_union(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
stddev(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: decimal) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: float) → float

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: int) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
string_agg(arg1: bytes, arg2: bytes) → bytes

Concatenates all selected values using the provided delimiter.

+		Immutable
string_agg(arg1: string, arg2: string) → string

Concatenates all selected values using the provided delimiter.

+		Immutable
sum(arg1: decimal) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: float) → float

Calculates the sum of the selected values.

+		Immutable
sum(arg1: int) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: interval) → interval

Calculates the sum of the selected values.

+		Immutable
sum_int(arg1: int) → int

Calculates the sum of the selected values.

+		Immutable
var_pop(arg1: decimal) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: float) → float

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: int) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_samp(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
variance(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
xor_agg(arg1: bytes) → bytes

Calculates the bitwise XOR of the selected values.

+		Immutable
xor_agg(arg1: int) → int

Calculates the bitwise XOR of the selected values.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-25.3/sql/functions.md b/src/current/_includes/cockroach-generated/release-25.3/sql/functions.md new file mode 100644 index 00000000000..14ad4f756cc --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.3/sql/functions.md @@ -0,0 +1,3616 @@ +### Array functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_append(array: bool[], elem: bool) → bool[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: bytes[], elem: bytes) → bytes[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: date[], elem: date) → date[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: decimal[], elem: decimal) → decimal[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: float[], elem: float) → float[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: inet[], elem: inet) → inet[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: int[], elem: int) → int[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: interval[], elem: interval) → interval[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: string[], elem: string) → string[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: time[], elem: time) → time[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamp[], elem: timestamp) → timestamp[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamptz[], elem: timestamptz) → timestamptz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: uuid[], elem: uuid) → uuid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: anyenum[], elem: anyenum) → anyenum[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: box2d[], elem: box2d) → box2d[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geography[], elem: geography) → geography[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geometry[], elem: geometry) → geometry[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: jsonb[], elem: jsonb) → jsonb[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: oid[], elem: oid) → oid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: refcursor[], elem: refcursor) → refcursor[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timetz[], elem: timetz) → timetz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: tuple[], elem: tuple) → tuple[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: varbit[], elem: varbit) → varbit[]

Appends elem to array, returning the result.

+		Immutable
array_cat(left: bool[], right: bool[]) → bool[]

Appends two arrays.

+		Immutable
array_cat(left: bytes[], right: bytes[]) → bytes[]

Appends two arrays.

+		Immutable
array_cat(left: date[], right: date[]) → date[]

Appends two arrays.

+		Immutable
array_cat(left: decimal[], right: decimal[]) → decimal[]

Appends two arrays.

+		Immutable
array_cat(left: float[], right: float[]) → float[]

Appends two arrays.

+		Immutable
array_cat(left: inet[], right: inet[]) → inet[]

Appends two arrays.

+		Immutable
array_cat(left: int[], right: int[]) → int[]

Appends two arrays.

+		Immutable
array_cat(left: interval[], right: interval[]) → interval[]

Appends two arrays.

+		Immutable
array_cat(left: string[], right: string[]) → string[]

Appends two arrays.

+		Immutable
array_cat(left: time[], right: time[]) → time[]

Appends two arrays.

+		Immutable
array_cat(left: timestamp[], right: timestamp[]) → timestamp[]

Appends two arrays.

+		Immutable
array_cat(left: timestamptz[], right: timestamptz[]) → timestamptz[]

Appends two arrays.

+		Immutable
array_cat(left: uuid[], right: uuid[]) → uuid[]

Appends two arrays.

+		Immutable
array_cat(left: anyenum[], right: anyenum[]) → anyenum[]

Appends two arrays.

+		Immutable
array_cat(left: box2d[], right: box2d[]) → box2d[]

Appends two arrays.

+		Immutable
array_cat(left: geography[], right: geography[]) → geography[]

Appends two arrays.

+		Immutable
array_cat(left: geometry[], right: geometry[]) → geometry[]

Appends two arrays.

+		Immutable
array_cat(left: jsonb[], right: jsonb[]) → jsonb[]

Appends two arrays.

+		Immutable
array_cat(left: oid[], right: oid[]) → oid[]

Appends two arrays.

+		Immutable
array_cat(left: pg_lsn[], right: pg_lsn[]) → pg_lsn[]

Appends two arrays.

+		Immutable
array_cat(left: refcursor[], right: refcursor[]) → refcursor[]

Appends two arrays.

+		Immutable
array_cat(left: timetz[], right: timetz[]) → timetz[]

Appends two arrays.

+		Immutable
array_cat(left: tuple[], right: tuple[]) → tuple[]

Appends two arrays.

+		Immutable
array_cat(left: varbit[], right: varbit[]) → varbit[]

Appends two arrays.

+		Immutable
array_length(input: anyelement[], array_dimension: int) → int

Calculates the length of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_lower(input: anyelement[], array_dimension: int) → int

Calculates the minimum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_position(array: bool[], elem: bool) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bool[], elem: bool, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: bytes[], elem: bytes) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bytes[], elem: bytes, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: date[], elem: date) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: date[], elem: date, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: decimal[], elem: decimal) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: decimal[], elem: decimal, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: float[], elem: float) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: float[], elem: float, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: inet[], elem: inet) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: inet[], elem: inet, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: int[], elem: int) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: int[], elem: int, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: interval[], elem: interval) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: interval[], elem: interval, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: string[], elem: string) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: string[], elem: string, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: time[], elem: time) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: time[], elem: time, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timestamp[], elem: timestamp) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamp[], elem: timestamp, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: uuid[], elem: uuid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: uuid[], elem: uuid, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: anyenum[], elem: anyenum) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: anyenum[], elem: anyenum, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: box2d[], elem: box2d) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: box2d[], elem: box2d, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: geography[], elem: geography) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geography[], elem: geography, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: geometry[], elem: geometry) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geometry[], elem: geometry, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: jsonb[], elem: jsonb) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: jsonb[], elem: jsonb, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: oid[], elem: oid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: oid[], elem: oid, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: refcursor[], elem: refcursor) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: refcursor[], elem: refcursor, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timetz[], elem: timetz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timetz[], elem: timetz, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: tuple[], elem: tuple) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: tuple[], elem: tuple, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: varbit[], elem: varbit) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: varbit[], elem: varbit, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_positions(array: bool[], elem: bool) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: bytes[], elem: bytes) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: date[], elem: date) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: decimal[], elem: decimal) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: float[], elem: float) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: inet[], elem: inet) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: int[], elem: int) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: interval[], elem: interval) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: string[], elem: string) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: time[], elem: time) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamp[], elem: timestamp) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamptz[], elem: timestamptz) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: uuid[], elem: uuid) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: anyenum[], elem: anyenum) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: box2d[], elem: box2d) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geography[], elem: geography) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geometry[], elem: geometry) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: jsonb[], elem: jsonb) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: oid[], elem: oid) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: pg_lsn[], elem: pg_lsn) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: refcursor[], elem: refcursor) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timetz[], elem: timetz) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: tuple[], elem: tuple) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: varbit[], elem: varbit) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_prepend(elem: bool, array: bool[]) → bool[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: bytes, array: bytes[]) → bytes[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: date, array: date[]) → date[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: decimal, array: decimal[]) → decimal[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: float, array: float[]) → float[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: inet, array: inet[]) → inet[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: int, array: int[]) → int[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: interval, array: interval[]) → interval[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: string, array: string[]) → string[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: time, array: time[]) → time[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamp, array: timestamp[]) → timestamp[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamptz, array: timestamptz[]) → timestamptz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: uuid, array: uuid[]) → uuid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: anyenum, array: anyenum[]) → anyenum[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: box2d, array: box2d[]) → box2d[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geography, array: geography[]) → geography[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geometry, array: geometry[]) → geometry[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: jsonb, array: jsonb[]) → jsonb[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: oid, array: oid[]) → oid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: pg_lsn, array: pg_lsn[]) → pg_lsn[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: refcursor, array: refcursor[]) → refcursor[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timetz, array: timetz[]) → timetz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: tuple, array: tuple[]) → tuple[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: varbit, array: varbit[]) → varbit[]

Prepends elem to array, returning the result.

+		Immutable
array_remove(array: bool[], elem: bool) → bool[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: bytes[], elem: bytes) → bytes[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: date[], elem: date) → date[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: decimal[], elem: decimal) → decimal[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: float[], elem: float) → float[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: inet[], elem: inet) → inet[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: int[], elem: int) → int[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: interval[], elem: interval) → interval[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: string[], elem: string) → string[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: time[], elem: time) → time[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamp[], elem: timestamp) → timestamp[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamptz[], elem: timestamptz) → timestamptz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: uuid[], elem: uuid) → uuid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: anyenum[], elem: anyenum) → anyenum[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: box2d[], elem: box2d) → box2d[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geography[], elem: geography) → geography[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geometry[], elem: geometry) → geometry[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: jsonb[], elem: jsonb) → jsonb[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: oid[], elem: oid) → oid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: refcursor[], elem: refcursor) → refcursor[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timetz[], elem: timetz) → timetz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: tuple[], elem: tuple) → tuple[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: varbit[], elem: varbit) → varbit[]

Remove from array all elements equal to elem.

+		Immutable
array_replace(array: bool[], toreplace: bool, replacewith: bool) → bool[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: bytes[], toreplace: bytes, replacewith: bytes) → bytes[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: date[], toreplace: date, replacewith: date) → date[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: decimal[], toreplace: decimal, replacewith: decimal) → decimal[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: float[], toreplace: float, replacewith: float) → float[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: inet[], toreplace: inet, replacewith: inet) → inet[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: int[], toreplace: int, replacewith: int) → int[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: interval[], toreplace: interval, replacewith: interval) → interval[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: string[], toreplace: string, replacewith: string) → string[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: time[], toreplace: time, replacewith: time) → time[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamp[], toreplace: timestamp, replacewith: timestamp) → timestamp[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamptz[], toreplace: timestamptz, replacewith: timestamptz) → timestamptz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: uuid[], toreplace: uuid, replacewith: uuid) → uuid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: anyenum[], toreplace: anyenum, replacewith: anyenum) → anyenum[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: box2d[], toreplace: box2d, replacewith: box2d) → box2d[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geography[], toreplace: geography, replacewith: geography) → geography[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geometry[], toreplace: geometry, replacewith: geometry) → geometry[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: jsonb[], toreplace: jsonb, replacewith: jsonb) → jsonb[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: oid[], toreplace: oid, replacewith: oid) → oid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: pg_lsn[], toreplace: pg_lsn, replacewith: pg_lsn) → pg_lsn[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: refcursor[], toreplace: refcursor, replacewith: refcursor) → refcursor[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timetz[], toreplace: timetz, replacewith: timetz) → timetz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: tuple[], toreplace: tuple, replacewith: tuple) → tuple[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: varbit[], toreplace: varbit, replacewith: varbit) → varbit[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_to_string(input: anyelement[], delim: string) → string

Join an array into a string with a delimiter.

+		Stable
array_to_string(input: anyelement[], delimiter: string, null: string) → string

Join an array into a string with a delimiter, replacing NULLs with a null string.

+		Stable
array_upper(input: anyelement[], array_dimension: int) → int

Calculates the maximum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
cardinality(input: anyelement[]) → int

Calculates the number of elements contained in input

+		Immutable
jsonb_array_to_string_array(input: jsonb) → string[]

Convert a JSONB array into a string array.

+		Immutable
string_to_array(str: string, delimiter: string) → string[]

Split a string into components on a delimiter.

+		Immutable
string_to_array(str: string, delimiter: string, null: string) → string[]

Split a string into components on a delimiter with a specified string to consider NULL.

+		Immutable
+ +### BOOL functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Matches case insensetively unescaped with pattern using escape as an escape token.

+		Immutable
inet_contained_by_or_equals(val: inet, container: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_contains_or_equals(container: inet, val: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_same_family(val: inet, val: inet) → bool

Checks if two IP addresses are of the same IP family.

+		Immutable
like_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
not_ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches case insensetively with pattern using escape as an escape token.

+		Immutable
not_like_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
not_similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
+ +### Comparison functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
greatest(anyelement...) → anyelement

Returns the element with the greatest value.

+		Immutable
least(anyelement...) → anyelement

Returns the element with the lowest value.

+		Immutable
num_nonnulls(any...) → int

Returns the number of nonnull arguments.

+		Immutable
num_nulls(any...) → int

Returns the number of null arguments.

+		Immutable
+ +### Cryptographic functions + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crypt(password: string, salt: string) → string

Generates a hash based on a password and salt. The hash algorithm and number of rounds if applicable are encoded in the salt.

+		Immutable
decrypt(data: bytes, key: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
decrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
digest(data: bytes, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
digest(data: string, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
encrypt(data: bytes, key: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
encrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
gen_random_bytes(count: int) → bytes

Returns count cryptographically strong random bytes. At most 1024 bytes can be extracted at a time.

+		Volatile
gen_salt(type: string) → string

Generates a salt for input into the crypt function using the default number of rounds.

+		Volatile
gen_salt(type: string, iter_count: int) → string

Generates a salt for input into the crypt function using iter_count number of rounds.

+		Volatile
hmac(data: bytes, key: bytes, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
hmac(data: string, key: string, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
+ +### DECIMAL functions + + + + + +
Function → ReturnsDescriptionVolatility
hlc_to_timestamp(hlc: decimal) → timestamptz

Returns a TimestampTZ representation of a CockroachDB HLC in decimal form.

+

Note that a TimestampTZ has less precision than a CockroachDB HLC. It is intended as +a convenience function to display HLCs in a print-friendly form. Use the decimal +value if you rely on the HLC for accuracy.

+		Immutable
+ +### Date and time functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
age(end: timestamptz, begin: timestamptz) → interval

Calculates the interval between begin and end, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use the timestamptz subtraction operator.

+		Immutable
age(val: timestamptz) → interval

Calculates the interval between val and the current time, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use now() - timestamptz.

+		Stable
clock_timestamp() → timestamp

Returns the current system time on one of the cluster nodes.

+		Volatile
clock_timestamp() → timestamptz

Returns the current system time on one of the cluster nodes.

+		Volatile
current_date() → date

Returns the date of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_timestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
date_part(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
date_part(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
date_trunc(element: string, input: date) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: interval) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: time) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero.

+

Compatible elements: hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamp) → timestamp

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamptz) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: timestamptz, timezone: string) → timestamptz

Truncates input to precision element in the specified timezone. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
experimental_follower_read_timestamp() → timestamptz

Same as follower_read_timestamp. This name is deprecated.

+		Volatile
experimental_strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
extract(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
extract(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
extract_duration(element: string, input: interval) → int

Extracts element from input. +Compatible elements: hour, minute, second, millisecond, microsecond. +This is deprecated in favor of extract which supports duration.

+		Immutable
follower_read_timestamp() → timestamptz

Returns a timestamp which is very likely to be safe to perform +against a follower replica.

+

This function is intended to be used with an AS OF SYSTEM TIME clause to perform +historical reads against a time which is recent but sufficiently old for reads +to be performed against the closest replica as opposed to the currently +leaseholder for a given range.

+

Note that this function requires an enterprise license on a CCL distribution to +return a result that is less likely the closest replica. It is otherwise +hardcoded as -4.8s from the statement time, which may not result in reading from the +nearest replica.

+		Volatile
localtimestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
make_date(year: int, month: int, day: int) → date

Create date (formatted according to ISO 8601) from year, month, and day fields (negative years signify BC).

+		Immutable
make_timestamp(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamp

Create timestamp (formatted according to ISO 8601) from year, month, day, hour, minute, and seconds fields (negative years signify BC).

+		Immutable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float, timezone: string) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
now() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
overlaps(s1: date, e1: date, s1: date, e2: date) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: date, e1: interval, s1: date, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: interval, s1: time, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: time, s1: time, e2: time) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: interval, s1: timestamp, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: timestamp, s1: timestamp, e2: timestamp) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamptz, e1: interval, s1: timestamptz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Stable
overlaps(s1: timestamptz, e1: timestamptz, s1: timestamptz, e2: timestamptz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: interval, s1: timetz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: timetz, s1: timetz, e2: timetz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
statement_timestamp() → timestamp

Returns the start time of the current statement.

+		Stable
statement_timestamp() → timestamptz

Returns the start time of the current statement.

+		Stable
strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
timeofday() → string

Returns the current system time on one of the cluster nodes as a string.

+		Stable
timezone(timezone: string, time: time) → timetz

Treat given time without time zone as located in the specified time zone.

+		Stable
timezone(timezone: string, timestamp: timestamp) → timestamptz

Treat given time stamp without time zone as located in the specified time zone.

+		Immutable
timezone(timezone: string, timestamptz: timestamptz) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Immutable
timezone(timezone: string, timestamptz_string: string) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Stable
timezone(timezone: string, timetz: timetz) → timetz

Convert given time with time zone to the new time zone.

+		Stable
to_char(date: date) → string

Convert an date to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(date: date, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_char(interval: interval) → string

Convert an interval to a string assuming the Postgres IntervalStyle.

+		Immutable
to_char(interval: interval, format: string) → string

Convert an interval to a string using the given format.

+		Stable
to_char(timestamp: timestamp) → string

Convert an timestamp to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(timestamp: timestamp, format: string) → string

Convert an timestamp to a string using the given format.

+		Stable
to_char(timestamptz: timestamptz, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_timestamp(timestamp: float) → timestamptz

Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to timestamp with time zone.

+		Immutable
transaction_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
with_max_staleness(max_staleness: interval) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_max_staleness(max_staleness: interval, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
+ +### Enum functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
enum_first(val: anyenum) → anyenum

Returns the first value of the input enum type.

+		Stable
enum_last(val: anyenum) → anyenum

Returns the last value of the input enum type.

+		Stable
enum_range(lower: anyenum, upper: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array between the two arguments (inclusive).

+		Stable
enum_range(val: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array.

+		Stable
+ +### FLOAT functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abs(val: decimal) → decimal

Calculates the absolute value of val.

+		Immutable
abs(val: float) → float

Calculates the absolute value of val.

+		Immutable
abs(val: int) → int

Calculates the absolute value of val.

+		Immutable
acos(val: float) → float

Calculates the inverse cosine of val.

+		Immutable
acosd(val: float) → float

Calculates the inverse cosine of val with the result in degrees

+		Immutable
acosh(val: float) → float

Calculates the inverse hyperbolic cosine of val.

+		Immutable
asin(val: float) → float

Calculates the inverse sine of val.

+		Immutable
asind(val: float) → float

Calculates the inverse sine of val with the result in degrees.

+		Immutable
asinh(val: float) → float

Calculates the inverse hyperbolic sine of val.

+		Immutable
atan(val: float) → float

Calculates the inverse tangent of val.

+		Immutable
atan2(x: float, y: float) → float

Calculates the inverse tangent of x/y.

+		Immutable
atan2d(x: float, y: float) → float

Calculates the inverse tangent of x/y with the result in degrees

+		Immutable
atand(val: float) → float

Calculates the inverse tangent of val with the result in degrees.

+		Immutable
atanh(val: float) → float

Calculates the inverse hyperbolic tangent of val.

+		Immutable
cbrt(val: decimal) → decimal

Calculates the cube root (∛) of val.

+		Immutable
cbrt(val: float) → float

Calculates the cube root (∛) of val.

+		Immutable
ceil(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
cos(val: float) → float

Calculates the cosine of val.

+		Immutable
cosd(val: float) → float

Calculates the cosine of val where val is in degrees.

+		Immutable
cosh(val: float) → float

Calculates the hyperbolic cosine of val.

+		Immutable
cot(val: float) → float

Calculates the cotangent of val.

+		Immutable
cotd(val: float) → float

Calculates the cotangent of val where val is in degrees.

+		Immutable
degrees(val: float) → float

Converts val as a radian value to a degree value.

+		Immutable
div(x: decimal, y: decimal) → decimal

Calculates the integer quotient of x/y.

+		Immutable
div(x: float, y: float) → float

Calculates the integer quotient of x/y.

+		Immutable
div(x: int, y: int) → int

Calculates the integer quotient of x/y.

+		Immutable
exp(val: decimal) → decimal

Calculates e ^ val.

+		Immutable
exp(val: float) → float

Calculates e ^ val.

+		Immutable
floor(val: decimal) → decimal

Calculates the largest integer not greater than val.

+		Immutable
floor(val: float) → float

Calculates the largest integer not greater than val.

+		Immutable
floor(val: int) → float

Calculates the largest integer not greater than val.

+		Immutable
isnan(val: decimal) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
isnan(val: float) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
ln(val: decimal) → decimal

Calculates the natural log of val.

+		Immutable
ln(val: float) → float

Calculates the natural log of val.

+		Immutable
log(b: decimal, x: decimal) → decimal

Calculates the base b log of val.

+		Immutable
log(b: float, x: float) → float

Calculates the base b log of val.

+		Immutable
log(val: decimal) → decimal

Calculates the base 10 log of val.

+		Immutable
log(val: float) → float

Calculates the base 10 log of val.

+		Immutable
mod(x: decimal, y: decimal) → decimal

Calculates x%y.

+		Immutable
mod(x: float, y: float) → float

Calculates x%y.

+		Immutable
mod(x: int, y: int) → int

Calculates x%y.

+		Immutable
pi() → float

Returns the value for pi (3.141592653589793).

+		Immutable
pow(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
pow(x: float, y: float) → float

Calculates x^y.

+		Immutable
pow(x: int, y: int) → int

Calculates x^y.

+		Immutable
power(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
power(x: float, y: float) → float

Calculates x^y.

+		Immutable
power(x: int, y: int) → int

Calculates x^y.

+		Immutable
radians(val: float) → float

Converts val as a degree value to a radians value.

+		Immutable
random() → float

Returns a random floating-point number between 0 (inclusive) and 1 (exclusive). Note that the value contains at most 53 bits of randomness.

+		Volatile
round(input: decimal, decimal_accuracy: int) → decimal

Keeps decimal_accuracy number of figures to the right of the zero position in input using half away from zero rounding. If decimal_accuracy is not in the range -2^31…(2^31-1), the results are undefined.

+		Immutable
round(input: float, decimal_accuracy: int) → float

Keeps decimal_accuracy number of figures to the right of the zero position in input using half to even (banker’s) rounding.

+		Immutable
round(val: decimal) → decimal

Rounds val to the nearest integer, half away from zero: round(+/-2.4) = +/-2, round(+/-2.5) = +/-3.

+		Immutable
round(val: float) → float

Rounds val to the nearest integer using half to even (banker’s) rounding.

+		Immutable
setseed(seed: float) → void

Sets the seed for subsequent random() calls in this session (value between -1.0 and 1.0, inclusive). There are no guarantees as to how this affects the seed of random() calls that appear in the same query as setseed().

+		Volatile
sign(val: decimal) → decimal

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: float) → float

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: int) → int

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sin(val: float) → float

Calculates the sine of val.

+		Immutable
sind(val: float) → float

Calculates the sine of val where val is in degrees.

+		Immutable
sinh(val: float) → float

Calculates the hyperbolic sine of val.

+		Immutable
sqrt(val: decimal) → decimal

Calculates the square root of val.

+		Immutable
sqrt(val: float) → float

Calculates the square root of val.

+		Immutable
tan(val: float) → float

Calculates the tangent of val.

+		Immutable
tand(val: float) → float

Calculates the tangent of val where val is in degrees.

+		Immutable
tanh(val: float) → float

Calculates the hyperbolic tangent of val.

+		Immutable
trunc(val: decimal) → decimal

Truncates the decimal values of val.

+		Immutable
trunc(val: decimal, scale: int) → decimal

Truncate val to scale decimal places

+		Immutable
trunc(val: float) → float

Truncates the decimal values of val.

+		Immutable
+ +### Full Text Search functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
phraseto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The <-> operator is inserted between each token in the input.

+		Immutable
phraseto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The <-> operator is inserted between each token in the input.

+		Stable
plainto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The & operator is inserted between each token in the input.

+		Immutable
plainto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The & operator is inserted between each token in the input.

+		Stable
to_tsquery(config: string, text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the specified configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Immutable
to_tsquery(text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the default configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Stable
to_tsvector(config: string, text: string) → tsvector

Converts text to a tsvector, normalizing words according to the specified configuration. Position information is included in the result.

+		Immutable
to_tsvector(text: string) → tsvector

Converts text to a tsvector, normalizing words according to the default configuration. Position information is included in the result.

+		Stable
ts_parse(parser_name: string, document: string) → tuple{int AS tokid, string AS token}

ts_parse parses the given document and returns a series of records, one for each token produced by parsing. Each record includes a tokid showing the assigned token type and a token which is the text of the token.

+		Stable
ts_rank(vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
+ +### Fuzzy String Matching functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
levenshtein(source: string, target: string) → int

Calculates the Levenshtein distance between two strings. Maximum input length is 255 characters.

+		Immutable
levenshtein(source: string, target: string, ins_cost: int, del_cost: int, sub_cost: int) → int

Calculates the Levenshtein distance between two strings. The cost parameters specify how much to charge for each edit operation. Maximum input length is 255 characters.

+		Immutable
metaphone(source: string, max_output_length: int) → string

Convert a string to its Metaphone code. Maximum input length is 255 characters

+		Immutable
soundex(source: string) → string

Convert a string to its Soundex code.

+		Immutable
+ +### ID generation functions + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
experimental_uuid_v4() → bytes

Returns a UUID.

+		Volatile
gen_random_ulid() → uuid

Generates a random ULID and returns it as a value of UUID type.

+		Volatile
gen_random_uuid() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
unique_rowid() → int

Returns a unique ID used by CockroachDB to generate unique row IDs if a Primary Key isn’t defined for the table. The value is a combination of the insert timestamp and the ID of the node executing the statement, which guarantees this combination is globally unique. However, there can be gaps and the order is not completely guaranteed.

+		Volatile
unordered_unique_rowid() → int

Returns a unique ID. The value is a combination of the insert timestamp (bit-reversed) and the ID of the node executing the statement, which guarantees this combination is globally unique. The way it is generated is statistically likely to not have any ordering relative to previously generated values.

+		Volatile
uuid_generate_v1() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. To avoid exposing the server’s real MAC address, this uses a random MAC address and a timestamp. Essentially, this is an alias for uuid_generate_v1mc.

+		Volatile
uuid_generate_v1mc() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. This uses a random MAC address and a timestamp.

+		Volatile
uuid_generate_v3(namespace: uuid, name: string) → uuid

Generates a version 3 UUID in the given namespace using the specified input name, with md5 as the hashing method. The namespace should be one of the special constants produced by the uuid_ns_*() functions.

+		Immutable
uuid_generate_v4() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
uuid_generate_v5(namespace: uuid, name: string) → uuid

Generates a version 5 UUID in the given namespace using the specified input name. This is similar to a version 3 UUID, except it uses SHA-1 for hashing.

+		Immutable
uuid_nil() → uuid

Returns a nil UUID constant.

+		Immutable
uuid_ns_dns() → uuid

Returns a constant designating the DNS namespace for UUIDs.

+		Immutable
uuid_ns_oid() → uuid

Returns a constant designating the ISO object identifier (OID) namespace for UUIDs. These are unrelated to the OID type used internally in the database.

+		Immutable
uuid_ns_url() → uuid

Returns a constant designating the URL namespace for UUIDs.

+		Immutable
uuid_ns_x500() → uuid

Returns a constant designating the X.500 distinguished name (DN) namespace for UUIDs.

+		Immutable
uuid_v4() → bytes

Returns a UUID.

+		Volatile
+ +### INET functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abbrev(val: inet) → string

Converts the combined IP address and prefix length to an abbreviated display format as text.For INET types, this will omit the prefix length if it’s not the default (32 or IPv4, 128 for IPv6)

+

For example, abbrev('192.168.1.2/24') returns '192.168.1.2/24'

+		Immutable
broadcast(val: inet) → inet

Gets the broadcast address for the network address represented by the value.

+

For example, broadcast('192.168.1.2/24') returns '192.168.1.255/24'

+		Immutable
family(val: inet) → int

Extracts the IP family of the value; 4 for IPv4, 6 for IPv6.

+

For example, family('::1') returns 6

+		Immutable
host(val: inet) → string

Extracts the address part of the combined address/prefixlen value as text.

+

For example, host('192.168.1.2/16') returns '192.168.1.2'

+		Immutable
hostmask(val: inet) → inet

Creates an IP host mask corresponding to the prefix length in the value.

+

For example, hostmask('192.168.1.2/16') returns '0.0.255.255'

+		Immutable
masklen(val: inet) → int

Retrieves the prefix length stored in the value.

+

For example, masklen('192.168.1.2/16') returns 16

+		Immutable
netmask(val: inet) → inet

Creates an IP network mask corresponding to the prefix length in the value.

+

For example, netmask('192.168.1.2/16') returns '255.255.0.0'

+		Immutable
set_masklen(val: inet, prefixlen: int) → inet

Sets the prefix length of val to prefixlen.

+

For example, set_masklen('192.168.1.2', 16) returns '192.168.1.2/16'.

+		Immutable
+ +### INT functions + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crc32c(bytes...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32c(string...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32ieee(bytes...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
crc32ieee(string...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
fnv32(bytes...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32(string...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32a(bytes...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv32a(string...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64(bytes...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64(string...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64a(bytes...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64a(string...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
width_bucket(operand: decimal, b1: decimal, b2: decimal, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2. Returns 0 or count+1 for an input outside that range.

+		Immutable
width_bucket(operand: int, b1: int, b2: int, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2.

+		Immutable
width_bucket(operand: anyelement, thresholds: anyelement[]) → int

return the bucket number to which operand would be assigned given an array listing the lower bounds of the buckets; returns 0 for an input less than the first lower bound; the thresholds array must be sorted, smallest first, or unexpected results will be obtained

+		Immutable
+ +### JSONB functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_to_json(array: anyelement[]) → jsonb

Returns the array as JSON or JSONB.

+		Stable
array_to_json(array: anyelement[], pretty_bool: bool) → jsonb

Returns the array as JSON or JSONB.

+		Stable
json_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
json_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
json_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
json_build_array(any...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
json_build_object(any...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
json_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
json_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
json_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
json_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
json_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
json_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
json_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
json_remove_path(val: jsonb, path: string[]) → jsonb

Remove the specified path from the JSON object.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
json_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
json_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
json_valid(string: string) → bool

Returns whether the given string is a valid JSON or not

+		Immutable
jsonb_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
jsonb_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
jsonb_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
jsonb_build_array(any...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
jsonb_build_object(any...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
jsonb_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
jsonb_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
jsonb_exists_any(json: jsonb, array: string[]) → bool

Returns whether any of the strings in the text array exist as top-level keys or array elements

+		Immutable
jsonb_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments. new_val will be inserted before path target.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb, insert_after: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If insert_after is true (default is false), new_val will be inserted after path target.

+		Immutable
jsonb_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
jsonb_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
jsonb_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
jsonb_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
jsonb_pretty(val: jsonb) → string

Returns the given JSON value as a STRING indented and with newlines.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
jsonb_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
jsonb_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
row_to_json(row: tuple) → jsonb

Returns the row as a JSON object.

+		Stable
to_json(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
to_jsonb(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
+ +### Jsonpath functions + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
jsonb_path_exists(target: jsonb, path: jsonpath) → bool

Checks whether the JSON path returns any item for the specified JSON value.

+		Immutable
jsonb_path_exists(target: jsonb, path: jsonpath, vars: jsonb) → bool

Checks whether the JSON path returns any item for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named +values to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_exists(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → bool

Checks whether the JSON path returns any item for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named +values to be substituted into the jsonpath expression. If the silent +argument is true, the function suppresses the following errors: +missing object field or array element, unexpected JSON item type, +datetime and numeric errors.

+		Immutable
jsonb_path_match(target: jsonb, path: jsonpath) → bool

Returns the SQL boolean result of a JSON path predicate check +for the specified JSON value. (This is useful only with predicate check +expressions, not SQL-standard JSON path expressions, since it will +either fail or return NULL if the path result is not a single boolean +value.)

+		Immutable
jsonb_path_match(target: jsonb, path: jsonpath, vars: jsonb) → bool

Returns the SQL boolean result of a JSON path predicate check +for the specified JSON value. (This is useful only with predicate check +expressions, not SQL-standard JSON path expressions, since it will +either fail or return NULL if the path result is not a single boolean +value.) The vars argument must be a JSON object, and its fields provide +named values to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_match(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → bool

Returns the SQL boolean result of a JSON path predicate check +for the specified JSON value. (This is useful only with predicate check +expressions, not SQL-standard JSON path expressions, since it will +either fail or return NULL if the path result is not a single boolean +value.) The vars argument must be a JSON object, and its fields provide +named values to be substituted into the jsonpath expression. If the +silent argument is true, the function suppresses the following errors: +missing object field or array element, unexpected JSON item type, +datetime and numeric errors.

+		Immutable
jsonb_path_query(target: jsonb, path: jsonpath) → jsonb

Returns all JSON items returned by the JSON path for the specified JSON value.

+		Immutable
jsonb_path_query(target: jsonb, path: jsonpath, vars: jsonb) → jsonb

Returns all JSON items returned by the JSON path for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_query(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → jsonb

Returns all JSON items returned by the JSON path for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression. If the silent argument is true, +the function suppresses the following errors: missing object field or array +element, unexpected JSON item type, datetime and numeric errors.

+		Immutable
jsonb_path_query_array(target: jsonb, path: jsonpath) → jsonb

Returns all JSON items returned by the JSON path for the +specified JSON value, as a JSON array.

+		Immutable
jsonb_path_query_array(target: jsonb, path: jsonpath, vars: jsonb) → jsonb

Returns all JSON items returned by the JSON path for the +specified JSON value, as a JSON array. The vars argument must be a +JSON object, and its fields provide named values to be substituted +into the jsonpath expression.

+		Immutable
jsonb_path_query_array(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → jsonb

Returns all JSON items returned by the JSON path for the +specified JSON value, as a JSON array. The vars argument must be a +JSON object, and its fields provide named values to be substituted +into the jsonpath expression. If the silent argument is true, the +function suppresses the following errors: missing object field or +array element, unexpected JSON item type, datetime and numeric errors.

+		Immutable
jsonb_path_query_first(target: jsonb, path: jsonpath) → jsonb

Returns the first JSON item returned by the JSON path for the +specified JSON value, or NULL if there are no results.

+		Immutable
jsonb_path_query_first(target: jsonb, path: jsonpath, vars: jsonb) → jsonb

Returns the first JSON item returned by the JSON path for the +specified JSON value, or NULL if there are no results. The vars +argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_query_first(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → jsonb

Returns the first JSON item returned by the JSON path for the +specified JSON value, or NULL if there are no results. The vars +argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression. If the silent argument is true, the +function suppresses the following errors: missing object field or +array element, unexpected JSON item type, datetime and numeric errors.

+		Immutable
+ +### Multi-region functions + + + + + + + +
Function → ReturnsDescriptionVolatility
default_to_database_primary_region(val: string) → string

Returns the given region if the region has been added to the current database. +Otherwise, this will return the primary region of the current database. +This will error if the current database is not a multi-region database.

+		Stable
gateway_region() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
rehome_row() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
+ +### PGVector functions + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cosine_distance(v1: vector, v2: vector) → float

Returns the cosine distance between the two vectors.

+		Immutable
inner_product(v1: vector, v2: vector) → float

Returns the inner product between the two vectors.

+		Immutable
l1_distance(v1: vector, v2: vector) → float

Returns the Manhattan distance between the two vectors.

+		Immutable
l2_distance(v1: vector, v2: vector) → float

Returns the Euclidean distance between the two vectors.

+		Immutable
vector_dims(vector: vector) → int

Returns the number of the dimensions in the vector.

+		Immutable
vector_norm(vector: vector) → float

Returns the Euclidean norm of the vector.

+		Immutable
+ +### STRING[] functions + + + + + + +
Function → ReturnsDescriptionVolatility
regexp_split_to_array(string: string, pattern: string) → string[]

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_array(string: string, pattern: string, flags: string) → string[]

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
+ +### Sequence functions + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
currval(sequence_name: string) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
currval(sequence_name: regclass) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
lastval() → int

Return value most recently obtained with nextval in this session.

+		Volatile
nextval(sequence_name: string) → int

Advances the given sequence and returns its new value.

+		Volatile
nextval(sequence_name: regclass) → int

Advances the given sequence and returns its new value.

+		Volatile
setval(sequence_name: string, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: string, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
setval(sequence_name: regclass, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: regclass, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
+ +### Set-returning functions + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
aclexplode(aclitems: string[]) → tuple{oid AS grantor, oid AS grantee, string AS privilege_type, bool AS is_grantable}

Produces a virtual table containing aclitem stuff (returns no rows as this feature is unsupported in CockroachDB)

+		Stable
generate_series(start: int, end: int) → int

Produces a virtual table containing the integer values from start to end, inclusive.

+		Immutable
generate_series(start: int, end: int, step: int) → int

Produces a virtual table containing the integer values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamp, end: timestamp, step: interval) → timestamp

Produces a virtual table containing the timestamp values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamptz, end: timestamptz, step: interval) → timestamptz

Produces a virtual table containing the timestampTZ values from start to end, inclusive, by increment of step.

+		Immutable
generate_subscripts(array: anyelement[]) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int, reverse: bool) → int

Returns a series comprising the given array’s subscripts.

+

When reverse is true, the series is returned in reverse order.

+		Immutable
information_schema._pg_expandarray(input: anyelement[]) → tuple{anyelement AS x, int AS n}

Returns the input array as a set of rows with an index

+		Immutable
json_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
json_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
json_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
jsonb_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
jsonb_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
jsonb_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
pg_get_keywords() → tuple{string AS word, string AS catcode, string AS catdesc}

Produces a virtual table containing the keywords known to the SQL parser.

+		Immutable
pg_options_to_table(options: string[]) → tuple{string AS option_name, string AS option_value}

Converts the options array format to a table.

+		Stable
regexp_split_to_table(string: string, pattern: string) → string

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_table(string: string, pattern: string, flags: string) → string

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
unnest(anyelement[], anyelement[], anyelement[]...) → tuple{anyelement AS unnest, anyelement AS unnest, anyelement AS unnest}

Returns the input arrays as a set of rows

+		Immutable
unnest(input: anyelement[]) → anyelement

Returns the input array as a set of rows

+		Immutable
workload_index_recs() → tuple{string AS index_rec, bytes[] AS fingerprint_ids}

Returns index recommendations and the fingerprint ids that the indexes will impact

+		Immutable
workload_index_recs(timestamptz: timestamptz) → tuple{string AS index_rec, bytes[] AS fingerprint_ids}

Returns index recommendations and the fingerprint ids that the indexes will impact

+		Immutable
+ +### Spatial functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
_st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
geometrytype(geometry: geometry) → string

Returns the type of geometry as a string.

+

This function utilizes the GEOS module.

+		Immutable
geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
postgis_addbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_dropbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_extensions_upgrade() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_full_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_geos_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_getbbox(geometry: geometry) → box2d

Returns a box2d encapsulating the given Geometry.

+		Immutable
postgis_hasbbox(geometry: geometry) → bool

Returns whether a given Geometry has a bounding box. False for points and empty geometries; always true otherwise.

+		Immutable
postgis_lib_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_lib_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_liblwgeom_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_libxml_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_proj_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_installed() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_released() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_wagyu_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
st_3dlength(geometry: geometry) → float

Returns the 3-dimensional or 2-dimensional length of the geometry.

+

Note ST_3DLength is only valid for LineString or MultiLineString. +For 2-D lines it will return the 2-D length (same as ST_Length and ST_Length2D)

+

This function utilizes the GEOS module.

+		Immutable
st_addmeasure(geometry: geometry, start: float, end: float) → geometry

Returns a copy of a LineString or MultiLineString with measure coordinates linearly interpolated between the specified start and end values. Any existing M coordinates will be overwritten.

+		Immutable
st_addpoint(line_string: geometry, point: geometry) → geometry

Adds a Point to the end of a LineString.

+		Immutable
st_addpoint(line_string: geometry, point: geometry, index: int) → geometry

Adds a Point to a LineString at the given 0-based index (-1 to append).

+		Immutable
st_affine(geometry: geometry, a: float, b: float, c: float, d: float, e: float, f: float, g: float, h: float, i: float, x_off: float, y_off: float, z_off: float) → geometry

Applies a 3D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b c x_off \ / x
+| d e f y_off | | y | +| g h i z_off | | z | +\ 0 0 0 1 / \ 0 /

+		Immutable
st_affine(geometry: geometry, a: float, b: float, d: float, e: float, x_off: float, y_off: float) → geometry

Applies a 2D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b x_off \ / x
+| d e y_off | | y | +\ 0 0 1 / \ 0 /

+		Immutable
st_angle(line1: geometry, line2: geometry) → float

Returns the clockwise angle between two LINESTRING geometries, treating them as vectors between their start- and endpoints. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry) → float

Returns the clockwise angle between the vectors formed by point2,point1 and point2,point3. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry, point4: geometry) → float

Returns the clockwise angle between the vectors formed by point1,point2 and point3,point4. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_area(geography: geography) → float

Returns the area of the given geography in meters^2. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geography: geography, use_spheroid: bool) → float

Returns the area of the given geography in meters^2.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_area(geometry_str: string) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_area2d(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_asbinary(geography: geography) → bytes

Returns the WKB representation of a given Geography.

+		Immutable
st_asbinary(geography: geography, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asbinary(geometry: geometry) → bytes

Returns the WKB representation of a given Geometry.

+		Immutable
st_asbinary(geometry: geometry, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asencodedpolyline(geometry: geometry) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Preserves 5 decimal places.

+		Immutable
st_asencodedpolyline(geometry: geometry, precision: int4) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+		Immutable
st_asewkb(geography: geography) → bytes

Returns the EWKB representation of a given Geography.

+		Immutable
st_asewkb(geometry: geometry) → bytes

Returns the EWKB representation of a given Geometry.

+		Immutable
st_asewkt(geography: geography) → string

Returns the EWKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_asewkt(geography: geography, max_decimal_digits: int) → string

Returns the EWKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry: geometry) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_asewkt(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry_str: string) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asewkt(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geography: geography) → string

Returns the GeoJSON representation of a given Geography. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option (default for Geography)
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326
    • +
+		Immutable
st_asgeojson(geometry: geometry) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+		Immutable
st_asgeojson(geometry_str: string) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(row: tuple) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(row: tuple, geo_column: string) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. Coordinates have a maximum of 9 decimal digits.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int, pretty: bool) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value. Output will be pretty printed in JSON if pretty is true.

+		Stable
st_ashexewkb(geography: geography) → string

Returns the EWKB representation in hex of a given Geography.

+		Immutable
st_ashexewkb(geography: geography, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexewkb(geometry: geometry) → string

Returns the EWKB representation in hex of a given Geometry.

+		Immutable
st_ashexewkb(geometry: geometry, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexwkb(geography: geography) → string

Returns the WKB representation in hex of a given Geography.

+		Immutable
st_ashexwkb(geometry: geometry) → string

Returns the WKB representation in hex of a given Geometry.

+		Immutable
st_askml(geography: geography) → string

Returns the KML representation of a given Geography.

+		Immutable
st_askml(geometry: geometry) → string

Returns the KML representation of a given Geometry.

+		Immutable
st_askml(geometry_str: string) → string

Returns the KML representation of a given Geometry.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping. +Uses 4096 as the tile extent size in tile coordinate space.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int, clip: bool) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds if required.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry can be transformed, and clipped if required.

+		Immutable
st_astext(geography: geography) → string

Returns the WKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_astext(geography: geography, max_decimal_digits: int) → string

Returns the WKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry: geometry) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_astext(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry_str: string) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astext(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int, precision_m: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_azimuth(geography_a: geography, geography_b: geography) → float

Returns the azimuth in radians of the segment defined by the given point geographies, or NULL if the two points are coincident. It is solved using the Inverse geodesic problem.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_azimuth(geometry_a: geometry, geometry_b: geometry) → float

Returns the azimuth in radians of the segment defined by the given point geometries, or NULL if the two points are coincident.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+		Immutable
st_bdpolyfromtext(str: string, srid: int) → geometry

Returns a Polygon from multilinestring WKT with a SRID. If the input is not a multilinestring an error will be thrown.

+		Immutable
st_boundary(geometry: geometry) → geometry

Returns the closure of the combinatorial boundary of this Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_box2dfromgeohash(geohash: string) → box2d

Return a Box2D from a GeoHash string with max precision.

+		Immutable
st_box2dfromgeohash(geohash: string, precision: int) → box2d

Return a Box2D from a GeoHash string with supplied precision.

+		Immutable
st_buffer(geography: geography, distance: float) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, buffer_style_params: string) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, quad_segs: int) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geometry: geometry, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry_str: string, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_centroid(geography: geography) → geography

Returns the centroid of given geography. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geography: geography, use_spheroid: bool) → geography

Returns the centroid of given geography.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geometry: geometry) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_centroid(geometry_str: string) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_clipbybox2d(geometry: geometry, box2d: box2d) → geometry

Clips the geometry to conform to the bounding box specified by box2d.

+		Immutable
st_closestpoint(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the 2-dimensional point on geometry_a that is closest to geometry_b. This is the first point of the shortest line.

+		Immutable
st_collectionextract(geometry: geometry, type: int) → geometry

Given a collection, returns a multitype consisting only of elements of the specified type. If there are no elements of the given type, an EMPTY geometry is returned. Types are specified as 1=POINT, 2=LINESTRING, 3=POLYGON - other types are not supported.

+		Immutable
st_collectionhomogenize(geometry: geometry) → geometry

Returns the “simplest” representation of a collection’s contents. Collections of a single type will be returned as an appopriate multitype, or a singleton if it only contains a single geometry.

+		Immutable
st_combinebbox(box2d: box2d, geometry: geometry) → box2d

Combines the current bounding box with the bounding box of the Geometry.

+		Immutable
st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_convexhull(geometry: geometry) → geometry

Returns a geometry that represents the Convex Hull of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_coorddim(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_difference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the difference of two Geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_dimension(geometry: geometry) → int

Returns the number of topological dimensions of a given Geometry.

+		Immutable
st_disjoint(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a does not overlap, touch or is within geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_distance(geography_a: geography, geography_b: geography) → float

Returns the distance in meters between geography_a and geography_b. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geography_a: geography, geography_b: geography, use_spheroid: bool) → float

Returns the distance in meters between geography_a and geography_b.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance between the given geometries.

+		Immutable
st_distance(geometry_a_str: string, geometry_b_str: string) → float

Returns the distance between the given geometries.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_distancesphere(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_distancespheroid(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a spheroid.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_endpoint(geometry: geometry) → geometry

Returns the last point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_envelope(box2d: box2d) → geometry

Returns a bounding geometry for the given box.

+		Immutable
st_envelope(geometry: geometry) → geometry

Returns a bounding envelope for the given geometry.

+

For geometries which have a POINT or LINESTRING bounding box (i.e. is a single point +or a horizontal or vertical line), a POINT or LINESTRING is returned. Otherwise, the +returned POLYGON will be ordered Bottom Left, Top Left, Top Right, Bottom Right, +Bottom Left.

+		Immutable
st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string, parent_only: bool) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+

The parent_only boolean is always ignored.

+		Stable
st_estimatedextent(table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_expand(box2d: box2d, delta: float) → box2d

Extends the box2d by delta units across all dimensions.

+		Immutable
st_expand(box2d: box2d, delta_x: float, delta_y: float) → box2d

Extends the box2d by delta_x units in the x dimension and delta_y units in the y dimension.

+		Immutable
st_expand(geometry: geometry, delta: float) → geometry

Extends the bounding box represented by the geometry by delta units across all dimensions, returning a Polygon representing the new bounding box.

+		Immutable
st_expand(geometry: geometry, delta_x: float, delta_y: float) → geometry

Extends the bounding box represented by the geometry by delta_x units in the x dimension and delta_y units in the y dimension, returning a Polygon representing the new bounding box.

+		Immutable
st_exteriorring(geometry: geometry) → geometry

Returns the exterior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon.

+		Immutable
st_flipcoordinates(geometry: geometry) → geometry

Returns a new geometry with the X and Y axes flipped.

+		Immutable
st_force2d(geometry: geometry) → geometry

Returns a Geometry that is forced into XY layout with any Z or M dimensions discarded.

+		Immutable
st_force3d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to 0. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry, defaultM: float) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to the specified default M value. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force4d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZM layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float, defaultM: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified Z value. If a M coordinate doesn’t exist, it will be set to the specified M value.

+		Immutable
st_forcecollection(geometry: geometry) → geometry

Converts the geometry into a GeometryCollection.

+		Immutable
st_forcepolygonccw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_forcepolygoncw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Frechet distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Frechet distance between the given geometries, with the given segment densification (range 0.0-1.0, -1 to disable).

+

Smaller densify_frac gives a more accurate Fréchet distance. However, the computation time and memory usage increases with the square of the number of subsegments.

+

This function utilizes the GEOS module.

+		Immutable
st_generatepoints(geometry: geometry, npoints: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. Uses system time as a seed. +The requested number of points must be not larger than 65336.

+		Volatile
st_generatepoints(geometry: geometry, npoints: int4, seed: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. +The requested number of points must be not larger than 65336.

+		Immutable
st_geogfromewkb(val: bytes) → geography

Returns the Geography from an EWKB representation.

+		Immutable
st_geogfromewkt(val: string) → geography

Returns the Geography from an EWKT representation.

+		Immutable
st_geogfromgeojson(val: string) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromgeojson(val: jsonb) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geogfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geogfromwkb(bytes: bytes, srid: int) → geography

Returns the Geography from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geogfromwkb(val: bytes) → geography

Returns the Geography from a WKB (or EWKB) representation.

+		Immutable
st_geographyfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geographyfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geohash(geography: geography) → string

Returns a GeoHash representation of the geeographywith full precision if a point is provided, or with variable precision based on the size of the feature.

+		Immutable
st_geohash(geography: geography, precision: int) → string

Returns a GeoHash representation of the geography with the supplied precision.

+		Immutable
st_geohash(geometry: geometry) → string

Returns a GeoHash representation of the geometry with full precision if a point is provided, or with variable precision based on the size of the feature. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geohash(geometry: geometry, precision: int) → string

Returns a GeoHash representation of the geometry with the supplied precision. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geomcollfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomcollfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geometryfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geometryfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geometryn(geometry: geometry, n: int) → geometry

Returns the n-th Geometry (1-indexed). Returns NULL if out of bounds.

+		Immutable
st_geometrytype(geometry: geometry) → string

Returns the type of geometry as a string prefixed with ST_.

+

This function utilizes the GEOS module.

+		Immutable
st_geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
st_geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
st_geomfromgeohash(geohash: string) → geometry

Return a POLYGON Geometry from a GeoHash string with max precision.

+		Immutable
st_geomfromgeohash(geohash: string, precision: int) → geometry

Return a POLYGON Geometry from a GeoHash string with supplied precision.

+		Immutable
st_geomfromgeojson(val: string) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromgeojson(val: jsonb) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geomfromwkb(bytes: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geomfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_hasarc(geometry: geometry) → bool

Returns whether there is a CIRCULARSTRING in the geometry.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Hausdorff distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Hausdorff distance between the given geometries, with the given segment densification (range 0.0-1.0).

+

This function utilizes the GEOS module.

+		Immutable
st_interiorringn(geometry: geometry, n: int) → geometry

Returns the n-th (1-indexed) interior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon, or the ring does not exist.

+		Immutable
st_intersection(geography_a: geography, geography_b: geography) → geography

Returns the point intersections of the given geographies.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a_str: string, geometry_b_str: string) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_isclosed(geometry: geometry) → bool

Returns whether the geometry is closed as defined by whether the start and end points are coincident. Points are considered closed, empty geometries are not. For collections and multi-types, all members must be closed, as must all polygon rings.

+		Immutable
st_iscollection(geometry: geometry) → bool

Returns whether the geometry is of a collection type (including multi-types).

+		Immutable
st_isempty(geometry: geometry) → bool

Returns whether the geometry is empty.

+		Immutable
st_ispolygonccw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are considered counter-clockwise.

+		Immutable
st_ispolygoncw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are considered clockwise.

+		Immutable
st_isring(geometry: geometry) → bool

Returns whether the geometry is a single linestring that is closed and simple, as defined by ST_IsClosed and ST_IsSimple.

+

This function utilizes the GEOS module.

+		Immutable
st_issimple(geometry: geometry) → bool

Returns true if the geometry has no anomalous geometric points, e.g. that it intersects with or lies tangent to itself.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry) → bool

Returns whether the geometry is valid as defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry, flags: int) → bool

Returns whether the geometry is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry) → string

Returns a string containing the reason the geometry is invalid along with the point of interest, or “Valid Geometry” if it is valid. Validity is defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry, flags: int) → string

Returns the reason the geometry is invalid or “Valid Geometry” if it is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidtrajectory(geometry: geometry) → bool

Returns whether the geometry encodes a valid trajectory.

+

Note the geometry must be a LineString with M coordinates.

+		Immutable
st_length(geography: geography) → float

Returns the length of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geography: geography, use_spheroid: bool) → float

Returns the length of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_length(geometry_str: string) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_length2d(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_linecrossingdirection(linestring_a: geometry, linestring_b: geometry) → int

Returns an interger value defining behavior of crossing of lines: +0: lines do not cross, +-1: linestring_b crosses linestring_a from right to left, +1: linestring_b crosses linestring_a from left to right, +-2: linestring_b crosses linestring_a multiple times from right to left, +2: linestring_b crosses linestring_a multiple times from left to right, +-3: linestring_b crosses linestring_a multiple times from left to left, +3: linestring_b crosses linestring_a multiple times from right to right.

+

Note that the top vertex of the segment touching another line does not count as a crossing, but the bottom vertex of segment touching another line is considered a crossing.

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string) → geometry

Creates a LineString from an Encoded Polyline string.

+

Returns valid results only if the polyline was encoded with 5 decimal places.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string, precision: int4) → geometry

Creates a LineString from an Encoded Polyline string.

+

Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefrommultipoint(geometry: geometry) → geometry

Creates a LineString from a MultiPoint geometry.

+		Immutable
st_linefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_lineinterpolatepoint(geometry: geometry, fraction: float) → geometry

Returns a point along the given LineString which is at given fraction of LineString’s total length.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float, repeat: bool) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length. If repeat is false (default true) then it returns first point.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_linelocatepoint(line: geometry, point: geometry) → float

Returns a float between 0 and 1 representing the location of the closest point on LineString to the given Point, as a fraction of total 2d line length.

+		Immutable
st_linemerge(geometry: geometry) → geometry

Returns a LineString or MultiLineString by joining together constituents of a MultiLineString with matching endpoints. If the input is not a MultiLineString or LineString, an empty GeometryCollection is returned.

+

This function utilizes the GEOS module.

+		Immutable
st_linestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: decimal, end_fraction: decimal) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: float, end_fraction: float) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_longestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the max distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the maximum distance between the geometry’s vertexes. The function will return the longest line that was discovered first when comparing maximum distances if more than one is found.

+		Immutable
st_m(geometry: geometry) → float

Returns the M coordinate of a geometry if it is a Point.

+		Immutable
st_makebox2d(geometry_a: geometry, geometry_b: geometry) → box2d

Creates a box2d from two points. Errors if arguments are not two non-empty points.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with SRID 0.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float, srid: int) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with the given SRID.

+		Immutable
st_makepoint(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float) → geometry

Returns a new Point with the given X, Y, and Z coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float, m: float) → geometry

Returns a new Point with the given X, Y, Z, and M coordinates.

+		Immutable
st_makepointm(x: float, y: float, m: float) → geometry

Returns a new Point with the given X, Y, and M coordinates.

+		Immutable
st_makepolygon(geometry: geometry) → geometry

Returns a new Polygon with the given outer LineString.

+		Immutable
st_makepolygon(outer: geometry, interior: anyelement[]) → geometry

Returns a new Polygon with the given outer LineString and interior (hole) LineString(s).

+		Immutable
st_makevalid(geometry: geometry) → geometry

Returns a valid form of the given geometry according to the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_maxdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the maximum distance across every pair of points comprising the given geometries. Note if the geometries are the same, it will return the maximum distance between the geometry’s vertexes.

+		Immutable
st_memsize(geometry: geometry) → int

Returns the amount of memory space (in bytes) the geometry takes.

+		Immutable
st_minimumboundingcircle(geometry: geometry) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingcircle(geometry: geometry, num_segs: int) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingradius(geometry: geometry) → tuple{geometry AS center, float AS radius}

Returns a record containing the center point and radius of the smallest circle that can fully contains the given geometry.

+		Immutable
st_minimumclearance(geometry: geometry) → float

Returns the minimum distance a vertex can move before producing an invalid geometry. Returns Infinity if no minimum clearance can be found (e.g. for a single point).

+		Immutable
st_minimumclearanceline(geometry: geometry) → geometry

Returns a LINESTRING spanning the minimum distance a vertex can move before producing an invalid geometry. If no minimum clearance can be found (e.g. for a single point), an empty LINESTRING is returned.

+		Immutable
st_mlinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mlinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mpointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multi(geometry: geometry) → geometry

Returns the geometry as a new multi-geometry, e.g converts a POINT to a MULTIPOINT. If the input is already a multitype or collection, it is returned as is.

+		Immutable
st_multilinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multipointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_ndims(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_node(geometry: geometry) → geometry

Adds a node on a geometry for each intersection. Resulting geometry is always a MultiLineString.

+		Immutable
st_normalize(geometry: geometry) → geometry

Returns the geometry in its normalized form.

+

This function utilizes the GEOS module.

+		Immutable
st_npoints(geometry: geometry) → int

Returns the number of points in a given Geometry. Works for any shape type.

+		Immutable
st_nrings(geometry: geometry) → int

Returns the number of rings in a Polygon Geometry. Returns 0 if the shape is not a Polygon.

+		Immutable
st_numgeometries(geometry: geometry) → int

Returns the number of shapes inside a given Geometry.

+		Immutable
st_numinteriorring(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numinteriorrings(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numpoints(geometry: geometry) → int

Returns the number of points in a LineString. Returns NULL if the Geometry is not a LineString.

+		Immutable
st_orderingequals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is exactly equal to geometry_b, having all coordinates in the same order, as well as the same type, SRID, bounding box, and so on.

+		Immutable
st_orientedenvelope(geometry: geometry) → geometry

Returns a minimum rotated rectangle enclosing a geometry. +Note that more than one minimum rotated rectangle may exist. +May return a Point or LineString in the case of degenerate inputs.

+		Immutable
st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_perimeter(geography: geography) → float

Returns the perimeter of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geography: geography, use_spheroid: bool) → float

Returns the perimeter of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_perimeter2d(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_point(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_pointfromgeohash(geohash: string) → geometry

Return a POINT Geometry from a GeoHash string with max precision.

+		Immutable
st_pointfromgeohash(geohash: string, precision: int) → geometry

Return a POINT Geometry from a GeoHash string with supplied precision.

+		Immutable
st_pointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Point, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_pointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointinsidecircle(geometry: geometry, x_coord: float, y_coord: float, radius: float) → bool

Returns the true if the geometry is a point and is inside the circle. Returns false otherwise.

+		Immutable
st_pointn(geometry: geometry, n: int) → geometry

Returns the n-th Point of a LineString (1-indexed). Returns NULL if out of bounds or not a LineString.

+		Immutable
st_pointonsurface(geometry: geometry) → geometry

Returns a point that intersects with the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_points(geometry: geometry) → geometry

Returns all coordinates in the given Geometry as a MultiPoint, including duplicates.

+		Immutable
st_polyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygon(geometry: geometry, srid: int) → geometry

Returns a new Polygon from the given LineString and sets its SRID. It is equivalent to ST_MakePolygon with a single argument followed by ST_SetSRID.

+		Immutable
st_polygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_project(geography: geography, distance: float, azimuth: float) → geography

Returns a point projected from a start point along a geodesic using a given distance and azimuth (bearing). +This is known as the direct geodesic problem.

+

The distance is given in meters. Negative values are supported.

+

The azimuth (also known as heading or bearing) is given in radians. It is measured clockwise from true north (azimuth zero). +East is azimuth π/2 (90 degrees); south is azimuth π (180 degrees); west is azimuth 3π/2 (270 degrees). +Negative azimuth values and values greater than 2π (360 degrees) are supported.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, bnr: int) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b using the given boundary node rule (1:OGC/MOD2, 2:Endpoint, 3:MultivalentEndpoint, 4:MonovalentEndpoint).

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, pattern: string) → bool

Returns whether the DE-9IM spatial relation between geometry_a and geometry_b matches the DE-9IM pattern.

+

This function utilizes the GEOS module.

+		Immutable
st_relatematch(intersection_matrix: string, pattern: string) → bool

Returns whether the given DE-9IM intersection matrix satisfies the given pattern.

+		Immutable
st_removepoint(line_string: geometry, index: int) → geometry

Removes the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_removerepeatedpoints(geometry: geometry) → geometry

Returns a geometry with repeated points removed.

+		Immutable
st_removerepeatedpoints(geometry: geometry, tolerance: float) → geometry

Returns a geometry with repeated points removed, within the given distance tolerance.

+		Immutable
st_reverse(geometry: geometry) → geometry

Returns a modified geometry by reversing the order of its vertices.

+		Immutable
st_rotate(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_point: geometry) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_x: float, origin_y: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotatex(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the x axis by a rotation angle.

+		Immutable
st_rotatey(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the y axis by a rotation angle.

+		Immutable
st_rotatez(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the z axis by a rotation angle.

+		Immutable
st_s2covering(geography: geography) → geography

Returns a geography which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geography: geography, settings: string) → geography

Returns a geography which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geography, 's2_max_level=15,s2_level_mod=3').

+		Immutable
st_s2covering(geometry: geometry) → geometry

Returns a geometry which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geometry: geometry, settings: string) → geometry

Returns a geometry which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geometry, 's2_max_level=15,s2_level_mod=3')

+		Immutable
st_scale(g: geometry, factor: geometry) → geometry

Returns a modified Geometry scaled by taking in a Geometry as the factor.

+		Immutable
st_scale(g: geometry, factor: geometry, origin: geometry) → geometry

Returns a modified Geometry scaled by the Geometry factor relative to a false origin.

+		Immutable
st_scale(geometry: geometry, x_factor: float, y_factor: float) → geometry

Returns a modified Geometry scaled by the given factors.

+		Immutable
st_segmentize(geography: geography, max_segment_length_meters: float) → geography

Returns a modified Geography having no segment longer than the given max_segment_length meters.

+

The calculations are done on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_segmentize(geometry: geometry, max_segment_length: float) → geometry

Returns a modified Geometry having no segment longer than the given max_segment_length. Length units are in units of spatial reference.

+		Immutable
st_setpoint(line_string: geometry, index: int, point: geometry) → geometry

Sets the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_setsrid(geography: geography, srid: int) → geography

Sets a Geography to a new SRID without transforming the coordinates.

+		Immutable
st_setsrid(geometry: geometry, srid: int) → geometry

Sets a Geometry to a new SRID without transforming the coordinates.

+		Immutable
st_sharedpaths(geometry_a: geometry, geometry_b: geometry) → geometry

Returns a collection containing paths shared by the two input geometries.

+

Those going in the same direction are in the first element of the collection, +those going in the opposite direction are in the second element. +The paths themselves are given in the direction of the first geometry.

+		Immutable
st_shiftlongitude(geometry: geometry) → geometry

Returns a modified version of a geometry in which the longitude (X coordinate) of each point is incremented by 360 if it is <0 and decremented by 360 if it is >180. The result is only meaningful if the coordinates are in longitude/latitude.

+		Immutable
st_shortestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the minimum distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the minimum distance between the geometry’s vertexes. The function will return the shortest line that was discovered first when comparing minimum distances if more than one is found.

+		Immutable
st_simplify(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm.

+

This function utilizes the GEOS module.

+		Immutable
st_simplify(geometry: geometry, tolerance: float, preserve_collapsed: bool) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, retaining objects that would be too small given the tolerance if preserve_collapsed is set to true.

+		Immutable
st_simplifypreservetopology(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, avoiding the creation of invalid geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_snap(input: geometry, target: geometry, tolerance: float) → geometry

Snaps the vertices and segments of input geometry the target geometry’s vertices. +Tolerance is used to control where snapping is performed. The result geometry is the input geometry with the vertices snapped. +If no snapping occurs then the input geometry is returned unchanged.

+		Immutable
st_snaptogrid(geometry: geometry, origin: geometry, size_x: float, size_y: float, size_z: float, size_m: float) → geometry

Snap a geometry to a grid defined by the given origin and X, Y, Z, and M cell sizes. Any dimension with a 0 cell size will not be snapped.

+		Immutable
st_snaptogrid(geometry: geometry, origin_x: float, origin_y: float, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y based on an origin of (origin_x, origin_y).

+		Immutable
st_snaptogrid(geometry: geometry, size: float) → geometry

Snap a geometry to a grid of the given size. The specified size is only used to snap X and Y coordinates.

+		Immutable
st_snaptogrid(geometry: geometry, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y.

+		Immutable
st_srid(geography: geography) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geography as defined in spatial_ref_sys table.

+		Immutable
st_srid(geometry: geometry) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geometry as defined in spatial_ref_sys table.

+		Immutable
st_startpoint(geometry: geometry) → geometry

Returns the first point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_subdivide(geometry: geometry) → geometry

Returns a geometry divided into parts, where each part contains no more than 256 vertices.

+		Immutable
st_subdivide(geometry: geometry, max_vertices: int4) → geometry

Returns a geometry divided into parts, where each part contains no more than the number of vertices provided.

+		Immutable
st_summary(geography: geography) → string

Returns a text summary of the contents of the geography.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_summary(geometry: geometry) → string

Returns a text summary of the contents of the geometry.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_swapordinates(geometry: geometry, swap_ordinate_string: string) → geometry

Returns a version of the given geometry with given ordinates swapped. +The swap_ordinate_string parameter is a 2-character string naming the ordinates to swap. Valid names are: x, y, z and m.

+		Immutable
st_symdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_symmetricdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4, bounds: geometry) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4, bounds: geometry, margin: float) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, srid: int) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates. The supplied SRID is set on the new geometry.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, srid: int) → geometry

Transforms a geometry into the given SRID coordinate reference system by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system referenced by the projection text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float, delta_z: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_transscale(geometry: geometry, delta_x: float, delta_y: float, x_factor: float, y_factor: float) → geometry

Translates the geometry using the deltaX and deltaY args, then scales it using the XFactor, YFactor args, working in 2D only.

+		Immutable
st_unaryunion(geometry: geometry) → geometry

Returns a union of the components for any geometry or geometry collection provided. Dissolves boundaries of a multipolygon.

+		Immutable
st_voronoilines(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoipolygons(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_wkbtosql(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_wkttosql(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_x(geometry: geometry) → float

Returns the X coordinate of a geometry if it is a Point.

+		Immutable
st_xmax(box2d: box2d) → float

Returns the maximum X ordinate of a box2d.

+		Immutable
st_xmax(geometry: geometry) → float

Returns the maximum X ordinate of a geometry.

+		Immutable
st_xmin(box2d: box2d) → float

Returns the minimum X ordinate of a box2d.

+		Immutable
st_xmin(geometry: geometry) → float

Returns the minimum X ordinate of a geometry.

+		Immutable
st_y(geometry: geometry) → float

Returns the Y coordinate of a geometry if it is a Point.

+		Immutable
st_ymax(box2d: box2d) → float

Returns the maximum Y ordinate of a box2d.

+		Immutable
st_ymax(geometry: geometry) → float

Returns the maximum Y ordinate of a geometry.

+		Immutable
st_ymin(box2d: box2d) → float

Returns the minimum Y ordinate of a box2d.

+		Immutable
st_ymin(geometry: geometry) → float

Returns the minimum Y ordinate of a geometry.

+		Immutable
st_z(geometry: geometry) → float

Returns the Z coordinate of a geometry if it is a Point.

+		Immutable
st_zmflag(geometry: geometry) → int2

Returns a code based on the ZM coordinate dimension of a geometry (XY = 0, XYM = 1, XYZ = 2, XYZM = 3).

+		Immutable
+ +### String and byte functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ascii(val: string) → int

Returns the character code of the first character in val. Despite the name, the function supports Unicode too.

+		Immutable
bit_count(val: bytes) → int

Calculates the number of bits set used to represent val.

+		Immutable
bit_count(val: varbit) → int

Calculates the number of bits set used to represent val.

+		Immutable
bit_length(val: bytes) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: string) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
bitmask_and(a: string, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: string, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
btrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning or end of input (applies recursively).

+

For example, btrim('doggie', 'eod') returns ggi.

+		Immutable
btrim(val: string) → string

Removes all spaces from the beginning and end of val.

+		Immutable
char_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
char_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
character_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
character_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
chr(val: int) → string

Returns the character with the code given in val. Inverse function of ascii().

+		Immutable
compress(data: bytes, codec: string) → bytes

Compress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
concat(any...) → string

Concatenates a comma-separated list of strings.

+		Immutable
concat_ws(string, any...) → string

Uses the first argument as a separator between the concatenation of the subsequent arguments.

+

For example concat_ws('!','wow','great') returns wow!great.

+		Immutable
convert_from(str: bytes, enc: string) → string

Decode the bytes in str into a string using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
convert_to(str: string, enc: string) → bytes

Encode the string str as a byte array using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
decode(text: string, format: string) → bytes

Decodes data using format (hex / escape / base64).

+		Immutable
decompress(data: bytes, codec: string) → bytes

Decompress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
difference(source: string, target: string) → int

Convert two strings to their Soundex codes and report the number of matching code positions.

+		Immutable
encode(data: bytes, format: string) → string

Encodes data using format (hex / escape / base64).

+		Immutable
format(string, any...) → string

Interprets the first argument as a format string similar to C sprintf and interpolates the remaining arguments.

+		Stable
from_ip(val: bytes) → string

Converts the byte string representation of an IP to its character string representation.

+		Immutable
from_uuid(val: bytes) → string

Converts the byte string representation of a UUID to its character string representation.

+		Immutable
get_bit(bit_string: varbit, index: int) → int

Extracts a bit at given index in the bit array.

+		Immutable
get_bit(byte_string: bytes, index: int) → int

Extracts a bit at the given index in the byte array.

+		Immutable
get_byte(byte_string: bytes, index: int) → int

Extracts a byte at the given index in the byte array.

+		Immutable
initcap(val: string) → string

Capitalizes the first letter of val.

+		Immutable
left(input: bytes, return_set: int) → bytes

Returns the first return_set bytes from input.

+		Immutable
left(input: string, return_set: int) → string

Returns the first return_set characters from input.

+		Immutable
length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
length(val: string) → int

Calculates the number of characters in val.

+		Immutable
length(val: varbit) → int

Calculates the number of bits in val.

+		Immutable
lower(val: string) → string

Converts all characters in val to their lower-case equivalents.

+		Immutable
lpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the left of string.If string is longer than length it is truncated.

+		Immutable
lpad(string: string, length: int, fill: string) → string

Pads string by adding fill to the left of string to make it length. If string is longer than length it is truncated.

+		Immutable
ltrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning (left-hand side) of input (applies recursively).

+

For example, ltrim('doggie', 'od') returns ggie.

+		Immutable
ltrim(val: string) → string

Removes all spaces from the beginning (left-hand side) of val.

+		Immutable
md5(bytes...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
md5(string...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
octet_length(val: bytes) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: string) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int) → string

Replaces characters in input with overlay_val starting at start_pos (begins at 1).

+

For example, overlay('doggie', 'CAT', 2) returns dCATie.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int, end_pos: int) → string

Deletes the characters in input between start_pos and end_pos (count starts at 1), and then insert overlay_val at start_pos.

+		Immutable
parse_date(string: string, datestyle: string) → date

Parses a date assuming it is in format specified by DateStyle.

+		Immutable
parse_date(val: string) → date

Parses a date assuming it is in MDY format.

+		Immutable
parse_ident(qualified_identifier: string) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. Extra characters after the last identifier are considered an error

+		Immutable
parse_ident(qualified_identifier: string, strict: bool) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. If strict is false, then extra characters after the last identifier are ignored.

+		Immutable
parse_interval(string: string, style: string) → interval

Convert a string to an interval using the given IntervalStyle.

+		Immutable
parse_interval(val: string) → interval

Convert a string to an interval assuming the Postgres IntervalStyle.

+		Immutable
parse_time(string: string, timestyle: string) → time

Parses a time assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_time(val: string) → time

Parses a time assuming the date (if any) is in MDY format.

+		Immutable
parse_timestamp(string: string, datestyle: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates formatted using the given DateStyle.

+		Immutable
parse_timestamp(val: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates are in MDY format.

+		Immutable
parse_timetz(string: string, timestyle: string) → timetz

Parses a timetz assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_timetz(val: string) → timetz

Parses a timetz assuming the date (if any) is in MDY format.

+		Immutable
prettify_statement(statement: string, line_width: int, align_mode: int, case_mode: int) → string

Prettifies a statement using a user-configured pretty-printing config. +Align mode values range from 0 - 3, representing no, partial, full, and extra alignment respectively. +Case mode values range between 0 - 1, representing lower casing and upper casing respectively.

+		Immutable
prettify_statement(val: string) → string

Prettifies a statement using a the default pretty-printing config.

+		Immutable
quote_ident(val: string) → string

Return val suitably quoted to serve as identifier in a SQL statement.

+		Immutable
quote_literal(val: string) → string

Return val suitably quoted to serve as string literal in a SQL statement.

+		Immutable
quote_literal(val: anyelement) → string

Coerce val to a string and then quote it as a literal.

+		Stable
quote_nullable(val: string) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Immutable
quote_nullable(val: anyelement) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Stable
regexp_extract(input: string, regex: string) → string

Returns the first match for the Regular Expression regex in input.

+		Immutable
regexp_replace(input: string, regex: string, replace: string) → string

Replaces matches for the Regular Expression regex in input with the Regular Expression replace.

+		Immutable
regexp_replace(input: string, regex: string, replace: string, flags: string) → string

Replaces matches for the regular expression regex in input with the regular expression replace using flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
repeat(input: string, repeat_counter: int) → string

Concatenates input repeat_counter number of times.

+

For example, repeat('dog', 2) returns dogdog.

+		Immutable
replace(input: string, find: string, replace: string) → string

Replaces all occurrences of find with replace in input

+		Immutable
reverse(val: string) → string

Reverses the order of the string’s characters.

+		Immutable
right(input: bytes, return_set: int) → bytes

Returns the last return_set bytes from input.

+		Immutable
right(input: string, return_set: int) → string

Returns the last return_set characters from input.

+		Immutable
rpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the right of string. If string is longer than length it is truncated.

+		Immutable
rpad(string: string, length: int, fill: string) → string

Pads string to length by adding fill to the right of string. If string is longer than length it is truncated.

+		Immutable
rtrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the end (right-hand side) of input (applies recursively).

+

For example, rtrim('doggie', 'ei') returns dogg.

+		Immutable
rtrim(val: string) → string

Removes all spaces from the end (right-hand side) of val.

+		Immutable
set_bit(bit_string: varbit, index: int, to_set: int) → varbit

Updates a bit at given index in the bit array.

+		Immutable
set_bit(byte_string: bytes, index: int, to_set: int) → bytes

Updates a bit at the given index in the byte array.

+		Immutable
set_byte(byte_string: bytes, index: int, to_set: int) → bytes

Updates a byte at the given index in the byte array.

+		Immutable
sha1(bytes...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha1(string...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha224(bytes...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha224(string...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha256(bytes...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha256(string...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha384(bytes...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha384(string...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha512(bytes...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
sha512(string...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
similar_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_to_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
split_part(input: string, delimiter: string, return_index_pos: int) → string

Splits input using delimiter and returns the field at return_index_pos (starting from 1). If return_index_pos is negative, it returns the |return_index_pos|'th field from the end.

+

For example, split_part('123.456.789.0', '.', 3) returns 789.

+		Immutable
strpos(input: bytes, find: bytes) → int

Calculates the position where the byte subarray find begins in input.

+		Immutable
strpos(input: string, find: string) → int

Calculates the position where the string find begins in input.

+

For example, strpos('doggie', 'gie') returns 4.

+		Immutable
strpos(input: varbit, find: varbit) → int

Calculates the position where the bit subarray find begins in input.

+		Immutable
substr(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substr(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substr(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substring(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substring(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring_index(input: string, delim: string, count: int) → string

Returns a substring of input before count occurrences of delim. +If count is positive, the leftmost part is returned. If count is negative, the rightmost part is returned.

+		Immutable
to_char_with_style(date: date, datestyle: string) → string

Convert an date to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_char_with_style(interval: interval, style: string) → string

Convert an interval to a string using the given IntervalStyle.

+		Immutable
to_char_with_style(timestamp: timestamp, datestyle: string) → string

Convert an timestamp to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_english(val: int) → string

This function enunciates the value of its argument using English cardinals.

+		Immutable
to_hex(val: bytes) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: int) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: string) → string

Converts val to its hexadecimal representation.

+		Immutable
to_ip(val: string) → bytes

Converts the character string representation of an IP to its byte string representation.

+		Immutable
to_uuid(val: string) → bytes

Converts the character string representation of a UUID to its byte string representation.

+		Immutable
translate(input: string, find: string, replace: string) → string

In input, replaces the first character from find with the first character in replace; repeat for each character in find.

+

For example, translate('doggie', 'dog', '123'); returns 1233ie.

+		Immutable
ulid_to_uuid(val: string) → uuid

Converts a ULID string to its UUID-encoded representation.

+		Immutable
unaccent(val: string) → string

Removes accents (diacritic signs) from the text provided in val.

+		Immutable
upper(val: string) → string

Converts all characters in val to their to their upper-case equivalents.

+		Immutable
+ +### System info functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cluster_logical_timestamp() → decimal

Returns the logical time of the current transaction as +a CockroachDB HLC in decimal form.

+

Note that uses of this function disable server-side optimizations and +may increase either contention or retry errors, or both.

+

Returns an error if run in a transaction with an isolation level weaker than SERIALIZABLE.

+		Volatile
current_database() → string

Returns the current database.

+		Stable
current_schema() → string

Returns the current schema.

+		Stable
current_schemas(include_pg_catalog: bool) → string[]

Returns the valid schemas in the search path.

+		Stable
current_user() → string

Returns the current user. This function is provided for compatibility with PostgreSQL.

+		Stable
session_user() → string

Returns the session user. This function is provided for compatibility with PostgreSQL.

+		Stable
to_regclass(text: string) → regtype

Translates a textual relation name to its OID

+		Stable
to_regnamespace(text: string) → regtype

Translates a textual schema name to its OID

+		Stable
to_regproc(text: string) → regtype

Translates a textual function or procedure name to its OID

+		Stable
to_regprocedure(text: string) → regtype

Translates a textual function or procedure name(with argument types) to its OID

+		Stable
to_regrole(text: string) → regtype

Translates a textual role name to its OID

+		Stable
to_regtype(text: string) → regtype

Translates a textual type name to its OID

+		Stable
version() → string

Returns the node’s version of CockroachDB.

+		Volatile
+ +### TIMETZ functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
current_time() → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time() → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_time(precision: int) → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time(precision: int) → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → timetz

Returns the current transaction’s time with time zone.

+		Stable
localtime(precision: int) → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime(precision: int) → timetz

Returns the current transaction’s time with time zone.

+		Stable
+ +### Trigrams functions + + + + + + +
Function → ReturnsDescriptionVolatility
show_trgm(input: string) → string[]

Returns an array of all the trigrams in the given string.

+		Immutable
similarity(left: string, right: string) → float

Returns a number that indicates how similar the two arguments are. The range of the result is zero (indicating that the two strings are completely dissimilar) to one (indicating that the two strings are identical).

+		Immutable
+ +### UUID functions + + + + + +
Function → ReturnsDescriptionVolatility
uuid_to_ulid(val: uuid) → string

Converts a UUID-encoded ULID to its string representation.

+		Immutable
+ +### Compatibility functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
col_description(table_oid: oid, column_number: int) → string

Returns the comment for a table column, which is specified by the OID of its table and its column number. (obj_description cannot be used for table columns, since columns do not have OIDs of their own.)

+		Stable
current_setting(setting_name: string) → string

System info

+		Stable
current_setting(setting_name: string, missing_ok: bool) → string

System info

+		Stable
format_type(type_oid: oid, typemod: int) → string

Returns the SQL name of a data type that is identified by its type OID and possibly a type modifier. Currently, the type modifier is ignored.

+		Stable
getdatabaseencoding() → string

Returns the current encoding name used by the database.

+		Stable
has_any_column_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_column_privilege(table: string, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: string, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_database_privilege(database: string, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(database: oid, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(user: string, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: string, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_foreign_data_wrapper_privilege(fdw: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(fdw: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_function_privilege(function: string, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(function: oid, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(user: string, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: string, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_language_privilege(language: string, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(language: oid, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(user: string, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: string, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_schema_privilege(schema: string, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(schema: oid, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_sequence_privilege(sequence: string, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(sequence: oid, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_server_privilege(server: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(server: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_table_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_tablespace_privilege(tablespace: string, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(tablespace: oid, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_type_privilege(type: string, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(type: oid, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(user: string, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: string, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
information_schema._pg_numeric_precision(typid: oid, typmod: int4) → int

Returns the precision of the given type with type modifier

+		Immutable
information_schema._pg_numeric_precision_radix(typid: oid, typmod: int4) → int

Returns the radix of the given type with type modifier

+		Immutable
information_schema._pg_numeric_scale(typid: oid, typmod: int4) → int

Returns the scale of the given type with type modifier

+		Immutable
nameconcatoid(name: string, oid: oid) → name

Used in the information_schema to produce specific_name columns, which are supposed to be unique per schema. The result is the same as ($1::text || ‘_’ || $2::text)::name except that, if it would not fit in 63 characters, we make it do so by truncating the name input (not the oid).

+		Immutable
obj_description(object_oid: oid) → string

Returns the comment for a database object specified by its OID alone. This is deprecated since there is no guarantee that OIDs are unique across different system catalogs; therefore, the wrong comment might be returned.

+		Stable
obj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a database object specified by its OID and the name of the containing system catalog. For example, obj_description(123456, ‘pg_class’) would retrieve the comment for the table with OID 123456.

+		Stable
oidvectortypes(vector: oidvector) → string

Generates a comma seperated string of type names from an oidvector.

+		Stable
pg_backend_pid() → int

Returns a numerical ID attached to this session. This ID is part of the query cancellation key used by the wire protocol. This function was only added for compatibility, and unlike in Postgres, the returned value does not correspond to a real process ID.

+		Stable
pg_collation_for(str: anyelement) → string

Returns the collation of the argument

+		Stable
pg_column_is_updatable(reloid: oid, attnum: int2, include_triggers: bool) → bool

Returns whether the given column can be updated.

+		Stable
pg_column_size(any...) → int

Return size in bytes of the column provided as an argument

+		Stable
pg_function_is_visible(oid: oid) → bool

Returns whether the function with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_get_function_arg_default(func_oid: oid, arg_num: int4) → string

Get textual representation of a function argument’s default value. The second argument of this function is the argument number among all arguments (i.e. proallargtypes, not proargtypes), starting with 1, because that’s how information_schema.sql uses it. Currently, this always returns NULL, since CockroachDB does not support default values.

+		Stable
pg_get_function_arguments(func_oid: oid) → string

Returns the argument list (with defaults) necessary to identify a function, in the form it would need to appear in within CREATE FUNCTION.

+		Stable
pg_get_function_identity_arguments(func_oid: oid) → string

Returns the argument list (without defaults) necessary to identify a function, in the form it would need to appear in within ALTER FUNCTION, for instance.

+		Stable
pg_get_function_result(func_oid: oid) → string

Returns the types of the result of the specified function.

+		Stable
pg_get_functiondef(func_oid: oid) → string

For user-defined functions, returns the definition of the specified function. For builtin functions, returns the name of the function.

+		Stable
pg_get_indexdef(index_oid: oid) → string

Gets the CREATE INDEX command for index

+		Stable
pg_get_indexdef(index_oid: oid, column_no: int, pretty_bool: bool) → string

Gets the CREATE INDEX command for index, or definition of just one index column when given a non-zero column number

+		Stable
pg_get_serial_sequence(table_name: string, column_name: string) → string

Returns the name of the sequence used by the given column_name in the table table_name.

+		Stable
pg_get_viewdef(view_oid: oid) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_get_viewdef(view_oid: oid, pretty_bool: bool) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_has_role(role: string, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(role: oid, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(user: string, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: string, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_is_other_temp_schema(oid: oid) → bool

Returns true if the given OID is the OID of another session’s temporary schema. (This can be useful, for example, to exclude other sessions’ temporary tables from a catalog display.)

+		Stable
pg_my_temp_schema() → oid

Returns the OID of the current session’s temporary schema, or zero if it has none (because it has not created any temporary tables).

+		Stable
pg_relation_is_updatable(reloid: oid, include_triggers: bool) → int4

Returns the update events the relation supports.

+		Stable
pg_sequence_last_value(sequence_oid: oid) → int

Returns the last value generated by a sequence, or NULL if the sequence has not been used yet.

+		Volatile
pg_sleep(seconds: float) → bool

pg_sleep makes the current session’s process sleep until seconds seconds have elapsed. seconds is a value of type double precision, so fractional-second delays can be specified.

+		Volatile
pg_table_is_visible(oid: oid) → bool

Returns whether the table with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_type_is_visible(oid: oid) → bool

Returns whether the type with the given OID belongs to one of the schemas on the search path.

+		Stable
set_config(setting_name: string, new_value: string, is_local: bool) → string

System info

+		Volatile
shobj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a shared database object specified by its OID and the name of the containing system catalog. This is just like obj_description except that it is used for retrieving comments on shared objects (e.g. databases).

+		Stable
+ diff --git a/src/current/_includes/cockroach-generated/release-25.3/sql/operators.md b/src/current/_includes/cockroach-generated/release-25.3/sql/operators.md new file mode 100644 index 00000000000..3bc5433dd67 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.3/sql/operators.md @@ -0,0 +1,664 @@ + + + + + +
#Return
int # intint
varbit # varbitvarbit
+ + + + +
#>Return
jsonb #> string[]jsonb
+ + + + +
#>>Return
jsonb #>> string[]string
+ + + + + + + + + +
%Return
decimal % decimaldecimal
decimal % intdecimal
float % floatfloat
int % decimaldecimal
int % intint
string % stringbool
+ + + + + + +
&Return
inet & inetinet
int & intint
varbit & varbitvarbit
+ + + + + + + + + +
&&Return
anyelement && anyelementbool
box2d && box2dbool
box2d && geometrybool
geometry && box2dbool
geometry && geometrybool
inet && inetbool
+ + + + + + + + + + + + + + + +
*Return
decimal * decimaldecimal
decimal * intdecimal
decimal * intervalinterval
float * floatfloat
float * intervalinterval
int * decimaldecimal
int * intint
int * intervalinterval
interval * decimalinterval
interval * floatinterval
interval * intinterval
vector * vectorvector
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Return
+decimaldecimal
+floatfloat
+intint
+intervalinterval
date + intdate
date + intervaltimestamp
date + timetimestamp
date + timetztimestamptz
decimal + decimaldecimal
decimal + intdecimal
decimal + pg_lsnpg_lsn
float + floatfloat
inet + intinet
int + datedate
int + decimaldecimal
int + inetinet
int + intint
interval + datetimestamp
interval + intervalinterval
interval + timetime
interval + timestamptimestamp
interval + timestamptztimestamptz
interval + timetztimetz
pg_lsn + decimalpg_lsn
time + datetimestamp
time + intervaltime
timestamp + intervaltimestamp
timestamptz + intervaltimestamptz
timetz + datetimestamptz
timetz + intervaltimetz
vector + vectorvector
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
-Return
-decimaldecimal
-floatfloat
-intint
-intervalinterval
date - dateint
date - intdate
date - intervaltimestamp
date - timetimestamp
decimal - decimaldecimal
decimal - intdecimal
float - floatfloat
inet - inetint
inet - intinet
int - decimaldecimal
int - intint
interval - intervalinterval
jsonb - intjsonb
jsonb - stringjsonb
jsonb - string[]jsonb
pg_lsn - decimalpg_lsn
pg_lsn - pg_lsndecimal
time - intervaltime
time - timeinterval
timestamp - intervaltimestamp
timestamp - timestampinterval
timestamp - timestamptzinterval
timestamptz - intervaltimestamptz
timestamptz - timestampinterval
timestamptz - timestamptzinterval
timetz - intervaltimetz
vector - vectorvector
+ + + + + +
->Return
jsonb -> intjsonb
jsonb -> stringjsonb
+ + + + + +
->>Return
jsonb ->> intstring
jsonb ->> stringstring
+ + + + + + + + + + +
/Return
decimal / decimaldecimal
decimal / intdecimal
float / floatfloat
int / decimaldecimal
int / intdecimal
interval / floatinterval
interval / intinterval
+ + + + + + + + +
//Return
decimal // decimaldecimal
decimal // intdecimal
float // floatfloat
int // decimaldecimal
int // intint
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<Return
anyenum < anyenumbool
bool < boolbool
bool[] < bool[]bool
box2d < box2dbool
bpchar < bpcharbool
bytes < bytesbool
bytes[] < bytes[]bool
collatedstring < collatedstringbool
collatedstring{*} < collatedstring{*}bool
date < datebool
date < timestampbool
date < timestamptzbool
date[] < date[]bool
decimal < decimalbool
decimal < floatbool
decimal < intbool
decimal[] < decimal[]bool
float < decimalbool
float < floatbool
float < intbool
float[] < float[]bool
geography < geographybool
geometry < geometrybool
inet < inetbool
inet[] < inet[]bool
int < decimalbool
int < floatbool
int < intbool
int < oidbool
int[] < int[]bool
interval < intervalbool
interval[] < interval[]bool
jsonb < jsonbbool
oid < intbool
oid < oidbool
pg_lsn < pg_lsnbool
refcursor < refcursorbool
string < stringbool
string[] < string[]bool
time < timebool
time < timetzbool
time[] < time[]bool
timestamp < datebool
timestamp < timestampbool
timestamp < timestamptzbool
timestamp[] < timestamp[]bool
timestamptz < datebool
timestamptz < timestampbool
timestamptz < timestamptzbool
timestamptz < timestamptzbool
timetz < timebool
timetz < timetzbool
tuple < tuplebool
uuid < uuidbool
uuid[] < uuid[]bool
varbit < varbitbool
vector < vectorbool
+ + + + +
<#>Return
vector <#> vectorfloat
+ + + + +
<->Return
vector <-> vectorfloat
+ + + + + + +
<<Return
inet << inetbool
int << intint
varbit << intvarbit
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<=Return
anyenum <= anyenumbool
bool <= boolbool
bool[] <= bool[]bool
box2d <= box2dbool
bpchar <= bpcharbool
bytes <= bytesbool
bytes[] <= bytes[]bool
collatedstring <= collatedstringbool
collatedstring{*} <= collatedstring{*}bool
date <= datebool
date <= timestampbool
date <= timestamptzbool
date[] <= date[]bool
decimal <= decimalbool
decimal <= floatbool
decimal <= intbool
decimal[] <= decimal[]bool
float <= decimalbool
float <= floatbool
float <= intbool
float[] <= float[]bool
geography <= geographybool
geometry <= geometrybool
inet <= inetbool
inet[] <= inet[]bool
int <= decimalbool
int <= floatbool
int <= intbool
int <= oidbool
int[] <= int[]bool
interval <= intervalbool
interval[] <= interval[]bool
jsonb <= jsonbbool
oid <= intbool
oid <= oidbool
pg_lsn <= pg_lsnbool
refcursor <= refcursorbool
string <= stringbool
string[] <= string[]bool
time <= timebool
time <= timetzbool
time[] <= time[]bool
timestamp <= datebool
timestamp <= timestampbool
timestamp <= timestamptzbool
timestamp[] <= timestamp[]bool
timestamptz <= datebool
timestamptz <= timestampbool
timestamptz <= timestamptzbool
timestamptz <= timestamptzbool
timetz <= timebool
timetz <= timetzbool
tuple <= tuplebool
uuid <= uuidbool
uuid[] <= uuid[]bool
varbit <= varbitbool
vector <= vectorbool
+ + + + +
<=>Return
vector <=> vectorfloat
+ + + + + +
<@Return
anyelement <@ anyelementbool
jsonb <@ jsonbbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
=Return
anyenum = anyenumbool
bool = boolbool
bool[] = bool[]bool
box2d = box2dbool
bpchar = bpcharbool
bytes = bytesbool
bytes[] = bytes[]bool
collatedstring = collatedstringbool
collatedstring{*} = collatedstring{*}bool
date = datebool
date = timestampbool
date = timestamptzbool
date[] = date[]bool
decimal = decimalbool
decimal = floatbool
decimal = intbool
decimal[] = decimal[]bool
float = decimalbool
float = floatbool
float = intbool
float[] = float[]bool
geography = geographybool
geometry = geometrybool
inet = inetbool
inet[] = inet[]bool
int = decimalbool
int = floatbool
int = intbool
int = oidbool
int[] = int[]bool
interval = intervalbool
interval[] = interval[]bool
jsonb = jsonbbool
oid = intbool
oid = oidbool
pg_lsn = pg_lsnbool
refcursor = refcursorbool
string = stringbool
string[] = string[]bool
time = timebool
time = timetzbool
time[] = time[]bool
timestamp = datebool
timestamp = timestampbool
timestamp = timestamptzbool
timestamp[] = timestamp[]bool
timestamptz = datebool
timestamptz = timestampbool
timestamptz = timestamptzbool
timestamptz = timestamptzbool
timetz = timebool
timetz = timetzbool
tsquery = tsquerybool
tsvector = tsvectorbool
tuple = tuplebool
uuid = uuidbool
uuid[] = uuid[]bool
varbit = varbitbool
vector = vectorbool
+ + + + + + +
>>Return
inet >> inetbool
int >> intint
varbit >> intvarbit
+ + + + +
?Return
jsonb ? stringbool
+ + + + +
?&Return
jsonb ?& string[]bool
+ + + + +
?|Return
jsonb ?| string[]bool
+ + + + + +
@>Return
anyelement @> anyelementbool
jsonb @> jsonbbool
+ + + + + +
@@Return
tsquery @@ tsvectorbool
tsvector @@ tsquerybool
+ + + + +
ILIKEReturn
string ILIKE stringbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
INReturn
anyenum IN tuplebool
bool IN tuplebool
box2d IN tuplebool
bpchar IN tuplebool
bytes IN tuplebool
collatedstring IN tuplebool
date IN tuplebool
decimal IN tuplebool
float IN tuplebool
geography IN tuplebool
geometry IN tuplebool
inet IN tuplebool
int IN tuplebool
interval IN tuplebool
jsonb IN tuplebool
oid IN tuplebool
pg_lsn IN tuplebool
refcursor IN tuplebool
string IN tuplebool
time IN tuplebool
timestamp IN tuplebool
timestamptz IN tuplebool
timetz IN tuplebool
tuple IN tuplebool
uuid IN tuplebool
varbit IN tuplebool
vector IN tuplebool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IS NOT DISTINCT FROMReturn
anyelement IS NOT DISTINCT FROM unknownbool
anyenum IS NOT DISTINCT FROM anyenumbool
bool IS NOT DISTINCT FROM boolbool
bool[] IS NOT DISTINCT FROM bool[]bool
box2d IS NOT DISTINCT FROM box2dbool
bpchar IS NOT DISTINCT FROM bpcharbool
bytes IS NOT DISTINCT FROM bytesbool
bytes[] IS NOT DISTINCT FROM bytes[]bool
collatedstring IS NOT DISTINCT FROM collatedstringbool
collatedstring{*} IS NOT DISTINCT FROM collatedstring{*}bool
date IS NOT DISTINCT FROM datebool
date IS NOT DISTINCT FROM timestampbool
date IS NOT DISTINCT FROM timestamptzbool
date[] IS NOT DISTINCT FROM date[]bool
decimal IS NOT DISTINCT FROM decimalbool
decimal IS NOT DISTINCT FROM floatbool
decimal IS NOT DISTINCT FROM intbool
decimal[] IS NOT DISTINCT FROM decimal[]bool
float IS NOT DISTINCT FROM decimalbool
float IS NOT DISTINCT FROM floatbool
float IS NOT DISTINCT FROM intbool
float[] IS NOT DISTINCT FROM float[]bool
geography IS NOT DISTINCT FROM geographybool
geometry IS NOT DISTINCT FROM geometrybool
inet IS NOT DISTINCT FROM inetbool
inet[] IS NOT DISTINCT FROM inet[]bool
int IS NOT DISTINCT FROM decimalbool
int IS NOT DISTINCT FROM floatbool
int IS NOT DISTINCT FROM intbool
int IS NOT DISTINCT FROM oidbool
int[] IS NOT DISTINCT FROM int[]bool
interval IS NOT DISTINCT FROM intervalbool
interval[] IS NOT DISTINCT FROM interval[]bool
jsonb IS NOT DISTINCT FROM jsonbbool
jsonpath IS NOT DISTINCT FROM jsonpathbool
oid IS NOT DISTINCT FROM intbool
oid IS NOT DISTINCT FROM oidbool
pg_lsn IS NOT DISTINCT FROM pg_lsnbool
refcursor IS NOT DISTINCT FROM refcursorbool
string IS NOT DISTINCT FROM stringbool
string[] IS NOT DISTINCT FROM string[]bool
time IS NOT DISTINCT FROM timebool
time IS NOT DISTINCT FROM timetzbool
time[] IS NOT DISTINCT FROM time[]bool
timestamp IS NOT DISTINCT FROM datebool
timestamp IS NOT DISTINCT FROM timestampbool
timestamp IS NOT DISTINCT FROM timestamptzbool
timestamp[] IS NOT DISTINCT FROM timestamp[]bool
timestamptz IS NOT DISTINCT FROM datebool
timestamptz IS NOT DISTINCT FROM timestampbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timetz IS NOT DISTINCT FROM timebool
timetz IS NOT DISTINCT FROM timetzbool
tsquery IS NOT DISTINCT FROM tsquerybool
tsvector IS NOT DISTINCT FROM tsvectorbool
tuple IS NOT DISTINCT FROM tuplebool
unknown IS NOT DISTINCT FROM unknownbool
unknown IS NOT DISTINCT FROM voidbool
uuid IS NOT DISTINCT FROM uuidbool
uuid[] IS NOT DISTINCT FROM uuid[]bool
varbit IS NOT DISTINCT FROM varbitbool
vector IS NOT DISTINCT FROM vectorbool
void IS NOT DISTINCT FROM unknownbool
+ + + + + +
LIKEReturn
collatedstring LIKE collatedstringbool
string LIKE stringbool
+ + + + +
SIMILAR TOReturn
string SIMILAR TO stringbool
+ + + + + + + + +
^Return
decimal ^ decimaldecimal
decimal ^ intdecimal
float ^ floatfloat
int ^ decimaldecimal
int ^ intint
+ + + + + + +
|Return
inet | inetinet
int | intint
varbit | varbitvarbit
+ + + + + +
|/Return
|/decimaldecimal
|/floatfloat
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
||Return
bool || bool[]bool[]
bool || stringstring
bool[] || boolbool[]
bool[] || bool[]bool[]
box2d || box2dbox2d
box2d || stringstring
bytes || bytesbytes
bytes || bytes[]bytes[]
bytes[] || bytesbytes[]
bytes[] || bytes[]bytes[]
date || date[]date[]
date || stringstring
date[] || datedate[]
date[] || date[]date[]
decimal || decimal[]decimal[]
decimal || stringstring
decimal[] || decimaldecimal[]
decimal[] || decimal[]decimal[]
float || float[]float[]
float || stringstring
float[] || floatfloat[]
float[] || float[]float[]
geography || geographygeography
geography || stringstring
geometry || geometrygeometry
geometry || stringstring
inet || inet[]inet[]
inet || stringstring
inet[] || inetinet[]
inet[] || inet[]inet[]
int || int[]int[]
int || stringstring
int[] || intint[]
int[] || int[]int[]
interval || interval[]interval[]
interval || stringstring
interval[] || intervalinterval[]
interval[] || interval[]interval[]
jsonb || jsonbjsonb
jsonb || stringstring
oid || oidoid
oid || stringstring
pg_lsn || pg_lsnpg_lsn
pg_lsn || stringstring
refcursor || refcursorrefcursor
refcursor || stringstring
string || boolstring
string || box2dstring
string || datestring
string || decimalstring
string || floatstring
string || geographystring
string || geometrystring
string || inetstring
string || intstring
string || intervalstring
string || jsonbstring
string || oidstring
string || pg_lsnstring
string || refcursorstring
string || stringstring
string || string[]string[]
string || timestring
string || timestampstring
string || timestamptzstring
string || timetzstring
string || tuplestring
string || uuidstring
string || varbitstring
string[] || stringstring[]
string[] || string[]string[]
time || stringstring
time || time[]time[]
time[] || timetime[]
time[] || time[]time[]
timestamp || stringstring
timestamp || timestamp[]timestamp[]
timestamp[] || timestamptimestamp[]
timestamp[] || timestamp[]timestamp[]
timestamptz || stringstring
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timetz || stringstring
timetz || timetztimetz
tuple || stringstring
uuid || stringstring
uuid || uuid[]uuid[]
uuid[] || uuiduuid[]
uuid[] || uuid[]uuid[]
varbit || stringstring
varbit || varbitvarbit
+ + + + + +
||/Return
||/decimaldecimal
||/floatfloat
+ + + + + + + + + + + +
~Return
~inetinet
~intint
~varbitvarbit
box2d ~ box2dbool
box2d ~ geometrybool
geometry ~ box2dbool
geometry ~ geometrybool
string ~ stringbool
+ + + + +
~*Return
string ~* stringbool
diff --git a/src/current/_includes/cockroach-generated/release-25.3/sql/window_functions.md b/src/current/_includes/cockroach-generated/release-25.3/sql/window_functions.md new file mode 100644 index 00000000000..e1032ff82de --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.3/sql/window_functions.md @@ -0,0 +1,413 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cume_dist() → float

Calculates the relative rank of the current row: (number of rows preceding or peer with current row) / (total rows).

+		Immutable
dense_rank() → int

Calculates the rank of the current row without gaps; this function counts peer groups.

+		Immutable
first_value(val: bool) → bool

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: bytes) → bytes

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: date) → date

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: decimal) → decimal

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: float) → float

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: inet) → inet

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: int) → int

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: interval) → interval

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: string) → string

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: time) → time

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: uuid) → uuid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: box2d) → box2d

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geography) → geography

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geometry) → geometry

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: oid) → oid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timetz) → timetz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: varbit) → varbit

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
lag(val: bool) → bool

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: bytes) → bytes

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: date) → date

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: date, n: int) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: decimal) → decimal

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: float) → float

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: float, n: int) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: inet) → inet

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: int) → int

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: int, n: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: interval) → interval

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: string) → string

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: string, n: int) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: time) → time

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: time, n: int) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamp) → timestamp

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz) → timestamptz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: uuid) → uuid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: box2d) → box2d

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geography) → geography

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geometry) → geometry

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: jsonb) → jsonb

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: oid) → oid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn) → pg_lsn

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: refcursor) → refcursor

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timetz) → timetz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: varbit) → varbit

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
last_value(val: bool) → bool

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: bytes) → bytes

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: date) → date

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: decimal) → decimal

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: float) → float

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: inet) → inet

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: int) → int

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: interval) → interval

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: string) → string

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: time) → time

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: uuid) → uuid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: box2d) → box2d

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geography) → geography

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geometry) → geometry

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: oid) → oid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timetz) → timetz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: varbit) → varbit

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
lead(val: bool) → bool

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: bytes) → bytes

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: date) → date

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: date, n: int) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: decimal) → decimal

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: float) → float

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: float, n: int) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: inet) → inet

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: int) → int

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: int, n: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: interval) → interval

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: string) → string

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: string, n: int) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: time) → time

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: time, n: int) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamp) → timestamp

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz) → timestamptz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: uuid) → uuid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: box2d) → box2d

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geography) → geography

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geometry) → geometry

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: jsonb) → jsonb

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: oid) → oid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn) → pg_lsn

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: refcursor) → refcursor

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timetz) → timetz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: varbit) → varbit

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
nth_value(val: bool, n: int) → bool

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: bytes, n: int) → bytes

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: date, n: int) → date

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: decimal, n: int) → decimal

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: float, n: int) → float

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: inet, n: int) → inet

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: int, n: int) → int

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: interval, n: int) → interval

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: string, n: int) → string

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: time, n: int) → time

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: uuid, n: int) → uuid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: box2d, n: int) → box2d

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geography, n: int) → geography

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geometry, n: int) → geometry

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: oid, n: int) → oid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timetz, n: int) → timetz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: varbit, n: int) → varbit

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
ntile(n: int) → int

Calculates an integer ranging from 1 to n, dividing the partition as equally as possible.

+		Immutable
percent_rank() → float

Calculates the relative rank of the current row: (rank - 1) / (total rows - 1).

+		Immutable
rank() → int

Calculates the rank of the current row with gaps; same as row_number of its first peer.

+		Immutable
row_number() → int

Calculates the number of the current row within its partition, counting from 1.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-25.4/eventlog.md b/src/current/_includes/cockroach-generated/release-25.4/eventlog.md new file mode 100644 index 00000000000..f543ad1fd3c --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.4/eventlog.md @@ -0,0 +1,3839 @@ +Certain notable events are reported using a structured format. +Commonly, these notable events are also copied to the table +`system.eventlog`, unless the cluster setting +`server.eventlog.enabled` is unset. + +Additionally, notable events are copied to specific external logging +channels in log messages, where they can be collected for further processing. + +The sections below document the possible notable event types +in this version of CockroachDB. For each event type, a table +documents the possible fields. A field may be omitted from +an event if its value is empty or zero. + +A field is also considered "Sensitive" if it may contain +application-specific information or personally identifiable information (PII). In that case, +the copy of the event sent to the external logging channel +will contain redaction markers in a format that is compatible +with the redaction facilities in [`cockroach debug zip`](cockroach-debug-zip.html) +and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html), +provided the `redactable` functionality is enabled on the logging sink. + +Events not documented on this page will have an unstructured format in log messages. + +## Changefeed telemetry events + +Events in this category pertain to changefeed usage and metrics. + +Events in this category are logged to the `TELEMETRY` channel. + + +### `alter_changefeed` + +An event of type `alter_changefeed` is an event for any ALTER CHANGEFEED statements that are run. + +Note: in version 26.1, these events will be moved to the `CHANGEFEED` channel. +To test compatability before this, set the cluster setting +`log.channel_compatibility_mode.enabled` to false. This will send the +events to `CHANGEFEED` instead of `TELEMETRY`. + + +| Field | Description | Sensitive | +|--|--|--| +| `PreviousDescription` | The description of the changefeed job before the ALTER CHANGEFEED. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `changefeed_canceled` + +An event of type `changefeed_canceled` is an event for any changefeed cancellations. + +Note: in version 26.1, these events will be moved to the `CHANGEFEED` channel. +To test compatability before this, set the cluster setting +`log.channel_compatibility_mode.enabled` to false. This will send the +events to `CHANGEFEED` instead of `TELEMETRY`. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `changefeed_emitted_bytes` + +An event of type `changefeed_emitted_bytes` is an event representing the bytes emitted by a changefeed over an interval. + +Note: in version 26.1, these events will be moved to the `CHANGEFEED` channel. +To test compatability before this, set the cluster setting +`log.channel_compatibility_mode.enabled` to false. This will send the +events to `CHANGEFEED` instead of `TELEMETRY`. + + +| Field | Description | Sensitive | +|--|--|--| +| `EmittedBytes` | The number of bytes emitted. | no | +| `EmittedMessages` | The number of messages emitted. | no | +| `LoggingInterval` | The time period in nanoseconds between emitting telemetry events of this type (per-aggregator). | no | +| `Closing` | Flag to indicate that the changefeed is closing. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `changefeed_failed` + +An event of type `changefeed_failed` is an event for any changefeed failure since the plan hook +was triggered. + +Note: in version 26.1, these events will be moved to the `CHANGEFEED` channel. +To test compatability before this, set the cluster setting +`log.channel_compatibility_mode.enabled` to false. This will send the +events to `CHANGEFEED` instead of `TELEMETRY`. + + +| Field | Description | Sensitive | +|--|--|--| +| `FailureType` | The reason / environment with which the changefeed failed (ex: connection_closed, changefeed_behind). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `create_changefeed` + +An event of type `create_changefeed` is an event for any CREATE CHANGEFEED query that +successfully starts running. Failed CREATE statements will show up as +ChangefeedFailed events. + +Note: in version 26.1, these events will be moved to the `CHANGEFEED` channel. +To test compatability before this, set the cluster setting +`log.channel_compatibility_mode.enabled` to false. This will send the +events to `CHANGEFEED` instead of `TELEMETRY`. + + +| Field | Description | Sensitive | +|--|--|--| +| `Transformation` | Flag representing whether the changefeed is using CDC queries. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +## Cluster-level events + +Events in this category pertain to an entire cluster and are +not relative to any particular tenant. + +In a multi-tenant setup, the `system.eventlog` table for individual +tenants cannot contain a copy of cluster-level events; conversely, +the `system.eventlog` table in the system tenant cannot contain the +SQL-level events for individual tenants. + +Events in this category are logged to the `OPS` channel. + + +### `certs_reload` + +An event of type `certs_reload` is recorded when the TLS certificates are +reloaded/rotated from disk. + + +| Field | Description | Sensitive | +|--|--|--| +| `Success` | Whether the operation completed without errors. | no | +| `ErrorMessage` | If an error was encountered, the text of the error. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `disk_slowness_cleared` + +An event of type `disk_slowness_cleared` is recorded when disk slowness in a store has cleared. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `disk_slowness_detected` + +An event of type `disk_slowness_detected` is recorded when a store observes disk slowness +events. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `low_disk_space` + +An event of type `low_disk_space` is emitted when a store is reaching capacity, as we reach +certain thresholds. It is emitted periodically while we are in a low disk +state. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | +| `PercentThreshold` | The free space percent threshold that we went under. | no | +| `AvailableBytes` | | no | +| `TotalBytes` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `node_decommissioned` + +An event of type `node_decommissioned` is recorded when a node is marked as +decommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_decommissioning` + +An event of type `node_decommissioning` is recorded when a node is marked as +decommissioning. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_join` + +An event of type `node_join` is recorded when a node joins the cluster. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_recommissioned` + +An event of type `node_recommissioned` is recorded when a decommissioning node is +recommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_restart` + +An event of type `node_restart` is recorded when an existing node rejoins the cluster +after being offline. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_connection_timeout` + +An event of type `node_shutdown_connection_timeout` is recorded when SQL connections remain open +during shutdown, after waiting for the server.shutdown.connections.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still open after waiting for the client to close them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.connections.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_transaction_timeout` + +An event of type `node_shutdown_transaction_timeout` is recorded when SQL transactions remain open +during shutdown, after waiting for the server.shutdown.transactions.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still running SQL transactions after waiting for the client to end them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.transactions.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `tenant_shared_service_start` + +An event of type `tenant_shared_service_start` is recorded when a tenant server +is started inside the same process as the KV layer. + + +| Field | Description | Sensitive | +|--|--|--| +| `OK` | Whether the startup was successful. | no | +| `ErrorText` | If the startup failed, the text of the error. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +### `tenant_shared_service_stop` + +An event of type `tenant_shared_service_stop` is recorded when a tenant server +is shut down inside the same process as the KV layer. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +## Contention events + +Aggregated information about contention events. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `aggregated_contention_info` + +An event of type `aggregated_contention_info` is recorded periodically when contention events +are resolved. + + +| Field | Description | Sensitive | +|--|--|--| +| `WaitingStmtFingerprintId` | | no | +| `WaitingTxnFingerprintId` | | no | +| `BlockingTxnFingerprintId` | | no | +| `ContendedKey` | | partially | +| `Duration` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Debugging events + +Events in this category pertain to debugging operations performed by +operators or (more commonly) Cockroach Labs employees. These operations can +e.g. directly access and mutate internal state, breaking system invariants. + +Events in this category are logged to the `OPS` channel. + + +### `debug_recover_replica` + +An event of type `debug_recover_replica` is recorded when unsafe loss of quorum recovery is performed. + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `StoreID` | | no | +| `SurvivorReplicaID` | | no | +| `UpdatedReplicaID` | | no | +| `StartKey` | | yes | +| `EndKey` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +### `debug_send_kv_batch` + +An event of type `debug_send_kv_batch` is recorded when an arbitrary KV BatchRequest is submitted +to the cluster via the `debug send-kv-batch` CLI command. + + +| Field | Description | Sensitive | +|--|--|--| +| `BatchRequest` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +## Health events + +Events in this category pertain to the health of one or more servers. + +Events in this category are logged to the `HEALTH` channel. + + +### `hot_ranges_stats` + +An event of type `hot_ranges_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `Qps` | | no | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | yes | +| `LeaseholderNodeID` | LeaseholderNodeID indicates the Node ID that is the current leaseholder for the given range. | no | +| `WritesPerSecond` | Writes per second is the recent number of keys written per second on this range. | no | +| `ReadsPerSecond` | Reads per second is the recent number of keys read per second on this range. | no | +| `WriteBytesPerSecond` | Write bytes per second is the recent number of bytes written per second on this range. | no | +| `ReadBytesPerSecond` | Read bytes per second is the recent number of bytes read per second on this range. | no | +| `CPUTimePerSecond` | CPU time per second is the recent cpu usage in nanoseconds of this range. | no | +| `Databases` | Databases for the range. | no | +| `Tables` | Tables for the range | no | +| `Indexes` | Indexes for the range | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `runtime_stats` + +An event of type `runtime_stats` is recorded every 10 seconds as server health metrics. + + +| Field | Description | Sensitive | +|--|--|--| +| `MemRSSBytes` | The process resident set size. Expressed as bytes. | no | +| `GoroutineCount` | The number of goroutines. | no | +| `MemStackSysBytes` | The stack system memory used. Expressed as bytes. | no | +| `GoAllocBytes` | The memory allocated by Go. Expressed as bytes. | no | +| `GoTotalBytes` | The total memory allocated by Go but not released. Expressed as bytes. | no | +| `GoStatsStaleness` | The staleness of the Go memory statistics. Expressed in seconds. | no | +| `HeapFragmentBytes` | The amount of heap fragmentation. Expressed as bytes. | no | +| `HeapReservedBytes` | The amount of heap reserved. Expressed as bytes. | no | +| `HeapReleasedBytes` | The amount of heap released. Expressed as bytes. | no | +| `CGoAllocBytes` | The memory allocated outside of Go. Expressed as bytes. | no | +| `CGoTotalBytes` | The total memory allocated outside of Go but not released. Expressed as bytes. | no | +| `CGoCallRate` | The total number of calls outside of Go over time. Expressed as operations per second. | no | +| `CPUUserPercent` | The user CPU percentage. | no | +| `CPUSysPercent` | The system CPU percentage. | no | +| `GCPausePercent` | The GC pause percentage. | no | +| `GCRunCount` | The total number of GC runs. | no | +| `NetHostRecvBytes` | The bytes received on all network interfaces since this process started. | no | +| `NetHostSendBytes` | The bytes sent on all network interfaces since this process started. | no | +| `GoLimitBytes` | The soft Go memory limit in bytes. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Job events + +Events in this category pertain to long-running jobs that are orchestrated by +a node's job registry. These system processes can create and/or modify stored +objects during the course of their execution. + +A job might choose to emit multiple events during its execution when +transitioning from one "state" to another. +Egs: IMPORT/RESTORE will emit events on job creation and successful +completion. If the job fails, events will be emitted on job creation, +failure, and successful revert. + +Events in this category are logged to the `OPS` channel. + + +### `import` + +An event of type `import` is recorded when an import job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `restore` + +An event of type `restore` is recorded when a restore job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `status_change` + +An event of type `status_change` is recorded when a job changes statuses. + + +| Field | Description | Sensitive | +|--|--|--| +| `JobID` | The ID of the job that is changing statuses. | no | +| `JobType` | The type of the job that is changing statuses. | no | +| `Description` | A human parsable description of the status change | partially | +| `PreviousStatus` | The status that the job is transitioning out of | no | +| `NewStatus` | The status that the job has transitioned into | no | +| `RunNum` | The run number of the job. | no | +| `Error` | An error that may have occurred while the job was running. | yes | +| `FinalResumeErr` | An error that occurred that requires the job to be reverted. | yes | +| `User` | User is the owner of the job. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Miscellaneous SQL events + +Events in this category report miscellaneous SQL events. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own system.eventlog table. + +Events in this category are logged to the `OPS` channel. + + +### `set_cluster_setting` + +An event of type `set_cluster_setting` is recorded when a cluster setting is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | +| `DefaultValue` | The current default value of the cluster setting. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `set_tenant_cluster_setting` + +An event of type `set_tenant_cluster_setting` is recorded when a cluster setting override +is changed, either for another tenant or for all tenants. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | +| `TenantId` | The target Tenant ID. Empty if targeting all tenants. | no | +| `AllTenants` | Whether the override applies to all tenants. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +## SQL Access Audit Events + +Events in this category are generated when a table has been +marked as audited via `ALTER TABLE ... EXPERIMENTAL_AUDIT SET`. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SENSITIVE_ACCESS` channel. + + +### `admin_query` + +An event of type `admin_query` is recorded when a user with admin privileges (the user +is directly or indirectly a member of the admin role) executes a query. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `role_based_audit_event` + +An event of type `role_based_audit_event` is an audit event recorded when an executed query belongs to a user whose role +membership(s) correspond to any role that is enabled to emit an audit log via the sql.log.user_audit +cluster setting. + + +| Field | Description | Sensitive | +|--|--|--| +| `Role` | The configured audit role that emitted this log. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sensitive_table_access` + +An event of type `sensitive_table_access` is recorded when an access is performed to +a table marked as audited. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table being audited. | yes | +| `AccessMode` | How the table was accessed (r=read / rw=read/write). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `unsafe_internals_accessed` + +UnsafeInternalsAccess is recorded when a query accesses unsafe internals +using the allow_unsafe_internals override. + + +| Field | Description | Sensitive | +|--|--|--| +| `Query` | The query that triggered the unsafe internals access. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `unsafe_internals_denied` + +An event of type `unsafe_internals_denied` is recorded when a query attempts to access unsafe internals +but lacks the appropriate session variables. + + +| Field | Description | Sensitive | +|--|--|--| +| `Query` | The query that triggered the unsafe internals access. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +## SQL Execution Log + +Events in this category report executed queries. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `query_execute` + +An event of type `query_execute` is recorded when a query is executed, +and the cluster setting `sql.log.all_statements.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `scan_row_count_misestimate` + +An event of type `scan_row_count_misestimate` is recorded when the optimizer's row count estimate +for a logical scan differs significantly from the actual number of rows read, +and cluster setting `sql.log.scan_row_count_misestimate.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The fully qualified name of the table being scanned. | no | +| `IndexName` | The name of the index being scanned. | no | +| `EstimatedRowCount` | The optimizer's estimated row count for the scan. | no | +| `ActualRowCount` | The actual number of rows read by all processors performing the scan. | no | +| `NanosSinceStatsCollected` | Time in nanoseconds that have passed since full stats were collected on the table. | no | +| `EstimatedStaleness` | Estimated fraction of stale rows in the table based on the time since stats were last collected. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +## SQL Logical Schema Changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the SQL logical +schema. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SQL_SCHEMA` channel. + + +### `alter_database_add_region` + +An event of type `alter_database_add_region` is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `RegionName` | The region being added. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_database_drop_region` + +AlterDatabaseAddRegion is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `RegionName` | The region being dropped. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_database_placement` + +An event of type `alter_database_placement` is recorded when the database placement is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `Placement` | The new placement policy. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_database_primary_region` + +An event of type `alter_database_primary_region` is recorded when a primary region is added/modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `PrimaryRegionName` | The new primary region. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_database_set_zone_config_extension` + +An event of type `alter_database_set_zone_config_extension` is recorded when a zone config extension is changed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `alter_database_survival_goal` + +An event of type `alter_database_survival_goal` is recorded when the survival goal is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `SurvivalGoal` | The new survival goal | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_function_options` + +An event of type `alter_function_options` is recorded when a user-defined function's options are +altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the affected function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_index` + +An event of type `alter_index` is recorded when an index is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_index_visible` + +AlterIndex is recorded when an index visibility is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `NotVisible` | Set true if index is not visible. NOTE: THIS FIELD IS DEPRECATED in favor of invisibility. | no | +| `Invisibility` | The new invisibility of the affected index. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_sequence` + +An event of type `alter_sequence` is recorded when a sequence is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_table` + +An event of type `alter_table` is recorded when a table is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update, if any. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_type` + +EventAlterType is recorded when a user-defined type is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_column` + +An event of type `comment_on_column` is recorded when a column is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected column. | no | +| `ColumnName` | The affected column. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_constraint` + +An event of type `comment_on_constraint` is recorded when an constraint is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected constraint. | no | +| `ConstraintName` | The name of the affected constraint. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_database` + +CommentOnTable is recorded when a database is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_index` + +An event of type `comment_on_index` is recorded when an index is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_schema` + + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | Name of the affected schema. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_table` + +An event of type `comment_on_table` is recorded when a table is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_type` + +An event of type `comment_on_type` is recorded when a type is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_database` + +An event of type `create_database` is recorded when a database is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the new database. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_function` + +An event of type `create_function` is recorded when a user-defined function is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the created function. | no | +| `IsReplace` | If the new function is a replace of an existing function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_index` + +An event of type `create_index` is recorded when an index is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the new index. | no | +| `IndexName` | The name of the new index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_policy` + +An event of type `create_policy` is recorded when a policy is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the policy's table. | no | +| `PolicyName` | Name of the created policy. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_schema` + +An event of type `create_schema` is recorded when a schema is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the new schema. | no | +| `Owner` | The name of the owner for the new schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_sequence` + +An event of type `create_sequence` is recorded when a sequence is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the new sequence. | no | +| `Owner` | The name of the owner for the new sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_statistics` + +An event of type `create_statistics` is recorded when statistics are collected for a +table. + +Events of this type are only collected when the cluster setting +`sql.stats.post_events.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table for which the statistics were created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_table` + +An event of type `create_table` is recorded when a table is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the new table. | no | +| `Owner` | The name of the owner for the new table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_trigger` + +An event of type `create_trigger` is recorded when a trigger is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the trigger's table. | no | +| `TriggerName` | Name of the created trigger. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_type` + +An event of type `create_type` is recorded when a user-defined type is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the new type. | no | +| `Owner` | The name of the owner for the new type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_view` + +An event of type `create_view` is recorded when a view is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the new view. | no | +| `Owner` | The name of the owner of the new view. | no | +| `ViewQuery` | The SQL selection clause used to define the view. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_database` + +An event of type `drop_database` is recorded when a database is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | no | +| `DroppedSchemaObjects` | The names of the schemas dropped by a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_function` + +An event of type `drop_function` is recorded when a user-defined function is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the dropped function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_index` + +An event of type `drop_index` is recorded when an index is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_policy` + +An event of type `drop_policy` is recorded when a policy is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the policy's table. | no | +| `PolicyName` | Name of the dropped policy. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_schema` + +An event of type `drop_schema` is recorded when a schema is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_sequence` + +An event of type `drop_sequence` is recorded when a sequence is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_table` + +An event of type `drop_table` is recorded when a table is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_trigger` + +An event of type `drop_trigger` is recorded when a trigger is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the trigger's table. | no | +| `TriggerName` | Name of the dropped trigger. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_type` + +An event of type `drop_type` is recorded when a user-defined type is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_view` + +An event of type `drop_view` is recorded when a view is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the affected view. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `finish_schema_change` + +An event of type `finish_schema_change` is recorded when a previously initiated schema +change has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to complete. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `finish_schema_change_rollback` + +An event of type `finish_schema_change_rollback` is recorded when a previously +initiated schema change rollback has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to rollback. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `force_delete_table_data_entry` + + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `refresh_materialized_view` + +An event of type `refresh_materialized_view` is recorded when a materialized view is refreshed. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the materialized view being refreshed. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `rename_database` + +An event of type `rename_database` is recorded when a database is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The old name of the affected database. | no | +| `NewDatabaseName` | The new name of the affected database. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `rename_function` + +An event of type `rename_function` is recorded when a user-defined function is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The old name of the affected function. | no | +| `NewFunctionName` | The new name of the affected function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `rename_schema` + +An event of type `rename_schema` is recorded when a schema is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The old name of the affected schema. | no | +| `NewSchemaName` | The new name of the affected schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `rename_table` + +An event of type `rename_table` is recorded when a table, sequence or view is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The old name of the affected table. | no | +| `NewTableName` | The new name of the affected table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `rename_type` + +An event of type `rename_type` is recorded when a user-defined type is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The old name of the affected type. | no | +| `NewTypeName` | The new name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `reverse_schema_change` + +An event of type `reverse_schema_change` is recorded when an in-progress schema change +encounters a problem and is reversed. + + +| Field | Description | Sensitive | +|--|--|--| +| `Error` | The error encountered that caused the schema change to be reversed. The specific format of the error is variable and can change across releases without warning. | partially | +| `SQLSTATE` | The SQLSTATE code for the error. | no | +| `LatencyNanos` | The amount of time the schema change job took before being reverted. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `set_schema` + +An event of type `set_schema` is recorded when a table, view, sequence or type's schema is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorName` | The old name of the affected descriptor. | no | +| `NewDescriptorName` | The new name of the affected descriptor. | no | +| `DescriptorType` | The descriptor type being changed (table, view, sequence, type). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `truncate_table` + +An event of type `truncate_table` is recorded when a table is truncated. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `unsafe_delete_descriptor` + +An event of type `unsafe_delete_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_delete_descriptor(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `unsafe_delete_namespace_entry` + +An event of type `unsafe_delete_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_delete_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `unsafe_upsert_descriptor` + +An event of type `unsafe_upsert_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_upsert_descriptor(). + + +| Field | Description | Sensitive | +|--|--|--| +| `PreviousDescriptor` | | yes | +| `NewDescriptor` | | yes | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `unsafe_upsert_namespace_entry` + +An event of type `unsafe_upsert_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_upsert_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `PreviousID` | | no | +| `Force` | | no | +| `FailedValidation` | | no | +| `ValidationErrors` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +## SQL Privilege changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the privilege +grants for stored objects. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `PRIVILEGES` channel. + + +### `alter_database_owner` + +An event of type `alter_database_owner` is recorded when a database's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database being affected. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_default_privileges` + +An event of type `alter_default_privileges` is recorded when default privileges are changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | +| `RoleName` | Either role_name should be populated or for_all_roles should be true. The role having its default privileges altered. | yes | +| `ForAllRoles` | Identifies if FOR ALL ROLES is used. | no | +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `alter_function_owner` + +AlterTableOwner is recorded when the owner of a user-defined function is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The name of the affected user-defined function. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_schema_owner` + +An event of type `alter_schema_owner` is recorded when a schema's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_table_owner` + +An event of type `alter_table_owner` is recorded when the owner of a table, view or sequence is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected object. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_type_owner` + +An event of type `alter_type_owner` is recorded when the owner of a user-defiend type is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `change_database_privilege` + +An event of type `change_database_privilege` is recorded when privileges are +added to / removed from a user for a database object. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_function_privilege` + + + +| Field | Description | Sensitive | +|--|--|--| +| `FuncName` | The name of the affected function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_schema_privilege` + +An event of type `change_schema_privilege` is recorded when privileges are added to / +removed from a user for a schema object. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_table_privilege` + +An event of type `change_table_privilege` is recorded when privileges are added to / removed +from a user for a table, sequence or view object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_type_privilege` + +An event of type `change_type_privilege` is recorded when privileges are added to / +removed from a user for a type object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +## SQL Session events + +Events in this category report SQL client connections +and sessions. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SESSIONS` channel. + + +### `client_authentication_failed` + +An event of type `client_authentication_failed` is reported when a client session +did not authenticate successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Reason` | The reason for the authentication failure. See below for possible values for type `AuthFailReason`. | no | +| `Detail` | The detailed error for the authentication failure. | partially | +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_info` + +An event of type `client_authentication_info` is reported for intermediate +steps during the authentication process. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used, once known. | no | +| `Info` | The authentication progress message. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_ok` + +An event of type `client_authentication_ok` is reported when a client session +was authenticated successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_connection_end` + +An event of type `client_connection_end` is reported when a client connection +is closed. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_connection_start` + +An event of type `client_connection_start` is reported when a client connection +is established. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_session_end` + +An event of type `client_session_end` is reported when a client session +is completed. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +## SQL Slow Query Log + +Events in this category report slow query execution. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +In version 26.1, these events will be moved to the `SQL_EXEC` channel. +To test compatability before this, set the cluster setting +`log.channel_compatibility_mode.enabled` to false. This will send the +events to `SQL_EXEC` instead of `SQL_PERF`. + +Events in this category are logged to the `SQL_PERF` channel. + + +### `large_row` + +An event of type `large_row` is recorded when a statement tries to write a row larger than +cluster setting `sql.guardrails.max_row_size_log` to the database. Multiple +LargeRow events will be recorded for statements writing multiple large rows. +LargeRow events are recorded before the transaction commits, so in the case +of transaction abort there will not be a corresponding row in the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query` + +An event of type `slow_query` is recorded when a query triggers the "slow query" condition. + +As of this writing, the condition requires: +- the cluster setting `sql.log.slow_query.latency_threshold` +set to a non-zero value, AND +- EITHER of the following conditions: +- the actual age of the query exceeds the configured threshold; AND/OR +- the query performs a full table/index scan AND the cluster setting +`sql.log.slow_query.experimental_full_table_scans.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit` + +An event of type `txn_rows_read_limit` is recorded when a transaction tries to read more rows than +cluster setting `sql.defaults.transaction_rows_read_log`. There will only be +a single record for a single transaction (unless it is retried) even if there +are more statement within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit` + +An event of type `txn_rows_written_limit` is recorded when a transaction tries to write more rows +than cluster setting `sql.defaults.transaction_rows_written_log`. There will +only be a single record for a single transaction (unless it is retried) even +if there are more mutation statements within the transaction that haven't +been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL Slow Query Log (Internal) + +Events in this category report slow query execution by +internal executors, i.e., when CockroachDB internally issues +SQL statements. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +In version 26.1, these events will be moved to the `SQL_EXEC` channel. +To test compatability before this, set the cluster setting +`log.channel_compatibility_mode.enabled` to false. This will send the +events to `SQL_EXEC` instead of `SQL_INTERNAL_PERF`. + +Events in this category are logged to the `SQL_INTERNAL_PERF` channel. + + +### `large_row_internal` + +An event of type `large_row_internal` is recorded when an internal query tries to write a row +larger than cluster settings `sql.guardrails.max_row_size_log` or +`sql.guardrails.max_row_size_err` to the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query_internal` + +An event of type `slow_query_internal` is recorded when a query triggers the "slow query" condition, +and the cluster setting `sql.log.slow_query.internal_queries.enabled` is +set. +See the documentation for the event type `slow_query` for details about +the "slow query" condition. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit_internal` + +An event of type `txn_rows_read_limit_internal` is recorded when an internal transaction tries to +read more rows than cluster setting `sql.defaults.transaction_rows_read_log` +or `sql.defaults.transaction_rows_read_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit_internal` + +An event of type `txn_rows_written_limit_internal` is recorded when an internal transaction tries to +write more rows than cluster setting +`sql.defaults.transaction_rows_written_log` or +`sql.defaults.transaction_rows_written_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL User and Role operations + +Events in this category pertain to SQL statements that modify the +properties of users and roles. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `USER_ADMIN` channel. + + +### `alter_role` + +An event of type `alter_role` is recorded when a role is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | +| `Options` | The options set on the user/role. | no | +| `SetInfo` | Information corresponding to an ALTER ROLE SET statement. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_role` + +An event of type `create_role` is recorded when a role is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the new user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_role` + +An event of type `drop_role` is recorded when a role is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `grant_role` + +An event of type `grant_role` is recorded when a role is granted. + + +| Field | Description | Sensitive | +|--|--|--| +| `GranteeRoles` | The roles being granted to. | yes | +| `Members` | The roles being granted. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `password_hash_converted` + +An event of type `password_hash_converted` is recorded when the password credentials +are automatically converted server-side. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the user/role whose credentials have been converted. | yes | +| `OldMethod` | The previous hash method. | no | +| `NewMethod` | The new hash method. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Storage telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `level_stats` + +An event of type `level_stats` contains per-level statistics for an LSM. + + +| Field | Description | Sensitive | +|--|--|--| +| `Level` | level is the level ID in a LSM (e.g. level(L0) == 0, etc.) | no | +| `NumFiles` | num_files is the number of files in the level (gauge). | no | +| `SizeBytes` | size_bytes is the size of the level, in bytes (gauge). | no | +| `Score` | score is the compaction score of the level (gauge). | no | +| `BytesIn` | bytes_in is the number of bytes written to this level (counter). | no | +| `BytesIngested` | bytes_ingested is the number of bytes ingested into this level (counter). | no | +| `BytesMoved` | bytes_moved is the number of bytes moved into this level via a move-compaction (counter). | no | +| `BytesRead` | bytes_read is the number of bytes read from this level, during compactions (counter). | no | +| `BytesCompacted` | bytes_compacted is the number of bytes written to this level during compactions (counter). | no | +| `BytesFlushed` | bytes flushed is the number of bytes flushed to this level. This value is always zero for levels other than L0 (counter). | no | +| `TablesCompacted` | tables_compacted is the count of tables compacted into this level (counter). | no | +| `TablesFlushed` | tables_flushed is the count of tables flushed into this level (counter). | no | +| `TablesIngested` | tables_ingested is the count of tables ingested into this level (counter). | no | +| `TablesMoved` | tables_moved is the count of tables moved into this level via move-compactions (counter). | no | +| `NumSublevels` | num_sublevel is the count of sublevels for the level. This value is always zero for levels other than L0 (gauge). | no | + + + +### `store_stats` + +An event of type `store_stats` contains per store stats. + +Note that because stats are scoped to the lifetime of the process, counters +(and certain gauges) will be reset across node restarts. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeId` | node_id is the ID of the node. | no | +| `StoreId` | store_id is the ID of the store. | no | +| `Levels` | levels is a nested message containing per-level statistics. | yes | +| `CacheSize` | cache_size is the size of the cache for the store, in bytes (gauge). | no | +| `CacheCount` | cache_count is the number of items in the cache (gauge). | no | +| `CacheHits` | cache_hits is the number of cache hits (counter). | no | +| `CacheMisses` | cache_misses is the number of cache misses (counter). | no | +| `CompactionCountDefault` | compaction_count_default is the count of default compactions (counter). | no | +| `CompactionCountDeleteOnly` | compaction_count_delete_only is the count of delete-only compactions (counter). | no | +| `CompactionCountElisionOnly` | compaction_count_elision_only is the count of elision-only compactions (counter). | no | +| `CompactionCountMove` | compaction_count_move is the count of move-compactions (counter). | no | +| `CompactionCountRead` | compaction_count_read is the count of read-compactions (counter). | no | +| `CompactionCountRewrite` | compaction_count_rewrite is the count of rewrite-compactions (counter). | no | +| `CompactionNumInProgress` | compactions_num_in_progress is the number of compactions in progress (gauge). | no | +| `CompactionMarkedFiles` | compaction_marked_files is the count of files marked for compaction (gauge). | no | +| `FlushCount` | flush_count is the number of flushes (counter). | no | +| `FlushIngestCount` | | no | +| `FlushIngestTableCount` | | no | +| `FlushIngestTableBytes` | | no | +| `IngestCount` | ingest_count is the number of successful ingest operations (counter). | no | +| `MemtableSize` | memtable_size is the total size allocated to all memtables and (large) batches, in bytes (gauge). | no | +| `MemtableCount` | memtable_count is the count of memtables (gauge). | no | +| `MemtableZombieCount` | memtable_zombie_count is the count of memtables no longer referenced by the current DB state, but still in use by an iterator (gauge). | no | +| `MemtableZombieSize` | memtable_zombie_size is the size, in bytes, of all zombie memtables (gauge). | no | +| `WalLiveCount` | wal_live_count is the count of live WAL files (gauge). | no | +| `WalLiveSize` | wal_live_size is the size, in bytes, of live data in WAL files. With WAL recycling, this value is less than the actual on-disk size of the WAL files (gauge). | no | +| `WalObsoleteCount` | wal_obsolete_count is the count of obsolete WAL files (gauge). | no | +| `WalObsoleteSize` | wal_obsolete_size is the size of obsolete WAL files, in bytes (gauge). | no | +| `WalPhysicalSize` | wal_physical_size is the size, in bytes, of the WAL files on disk (gauge). | no | +| `WalBytesIn` | wal_bytes_in is the number of logical bytes written to the WAL (counter). | no | +| `WalBytesWritten` | wal_bytes_written is the number of bytes written to the WAL (counter). | no | +| `TableObsoleteCount` | table_obsolete_count is the number of tables which are no longer referenced by the current DB state or any open iterators (gauge). | no | +| `TableObsoleteSize` | table_obsolete_size is the size, in bytes, of obsolete tables (gauge). | no | +| `TableZombieCount` | table_zombie_count is the number of tables no longer referenced by the current DB state, but are still in use by an open iterator (gauge). | no | +| `TableZombieSize` | table_zombie_size is the size, in bytes, of zombie tables (gauge). | no | +| `RangeKeySetsCount` | range_key_sets_count is the approximate count of internal range key sets in the store. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## TELEMETRY + +Events in this file are related to bulk ingest operations performance metrics. + +Events in this category are logged to the `TELEMETRY` channel. + + +### `bulk_ingest_completed` + +An event of type `bulk_ingest_completed` is an event that is logged when a bulk ingest job +(restore, import, etc.) completes successfully. +It captures key performance metrics for the operation. + + +| Field | Description | Sensitive | +|--|--|--| +| `JobID` | JobID is the ID of the bulk ingest job. | no | +| `JobType` | JobType identifies the type of bulk ingest job (e.g., "restore", "import"). | no | +| `NumRows` | NumRows is the number of rows successfully ingested. | no | +| `DurationSeconds` | Duration of the ingest operation in seconds. | no | +| `DataSizeMb` | Total logical size of data ingested in megabytes. | no | +| `NodeCount` | Number of nodes that participated in the ingest operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `captured_index_usage_stats` + +An event of type `captured_index_usage_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `TotalReadCount` | TotalReadCount is the number of times the index has been read. | no | +| `LastRead` | LastRead is the timestamp at which the index was last read. | no | +| `TableID` | TableID is the ID of the table on which the index was created. This is same as descpb.TableID and is unique within the cluster. | no | +| `IndexID` | IndexID is the ID of the index within the scope of the given table. | no | +| `DatabaseName` | DatabaseName is the name of the database in which the index was created. | no | +| `TableName` | TableName is the name of the table on which the index was created. | no | +| `IndexName` | IndexName is the name of the index within the scope of the given table. | no | +| `IndexType` | IndexType is the type of the index. Index types include "primary" and "secondary". | no | +| `IsUnique` | IsUnique indicates if the index has a UNIQUE constraint. | no | +| `IsInverted` | IsInverted indicates if the index is an inverted index. | no | +| `CreatedAt` | CreatedAt is the timestamp at which the index was created. | no | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `m_v_c_c_iterator_stats` + +Internal storage iteration statistics for a single execution. + + +| Field | Description | Sensitive | +|--|--|--| +| `StepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `StepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `BlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `BlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `KeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `ValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | + + + +### `recovery_event` + +An event of type `recovery_event` is an event that is logged on every invocation of BACKUP, +RESTORE, and on every BACKUP schedule creation, with the appropriate subset +of fields populated depending on the type of event. This event is is also +logged whenever a BACKUP and RESTORE job completes or fails. + + +| Field | Description | Sensitive | +|--|--|--| +| `RecoveryType` | RecoveryType is the type of recovery described by this event, which is one of - backup - scheduled_backup - create_schedule - restore

It can also be a job event corresponding to the recovery, which is one of - backup_job - scheduled_backup_job - restore_job | no | +| `TargetScope` | TargetScope is the largest scope of the targets that the user is backing up or restoring based on the following order: table < schema < database < full cluster. | no | +| `IsMultiregionTarget` | IsMultiregionTarget is true if any of the targets contain objects with multi-region primitives. | no | +| `TargetCount` | TargetCount is the number of targets the in the BACKUP/RESTORE. | no | +| `DestinationStorageTypes` | DestinationStorageTypes are the types of storage that the user is backing up to or restoring from. | no | +| `DestinationAuthTypes` | DestinationAuthTypes are the types of authentication methods that the user is using to access the destination storage. | no | +| `IsLocalityAware` | IsLocalityAware indicates if the BACKUP or RESTORE is locality aware. | no | +| `WithRevisionHistory` | WithRevisionHistory is true if the BACKUP includes revision history. | no | +| `HasEncryptionPassphrase` | HasEncryptionPassphrase is true if the user provided an encryption passphrase to encrypt/decrypt their backup. | no | +| `KMSType` | KMSType is the type of KMS the user is using to encrypt/decrypt their backup. | no | +| `KMSCount` | KMSCount is the number of KMS the user is using. | no | +| `Options` | Options contain all the names of the options specified by the user in the BACKUP or RESTORE statement. For options that are accompanied by a value, only those with non-empty values will be present.

It's important to note that there are no option values anywhere in the event payload. Future changes to telemetry should refrain from adding values to the payload unless they are properly redacted. | no | +| `JobID` | JobID is the ID of the BACKUP/RESTORE job. | no | +| `ResultStatus` | ResultStatus indicates whether the job succeeded or failed. | no | +| `ErrorText` | ErrorText is the text of the error that caused the job to fail. | partially | +| `RecurringCron` | RecurringCron is the crontab for the incremental backup. | no | +| `FullBackupCron` | FullBackupCron is the crontab for the full backup. | no | +| `CustomFirstRunTime` | CustomFirstRunTime is the timestamp for the user configured first run time. Expressed as nanoseconds since the Unix epoch. | no | +| `IgnoreExistingBackup` | IgnoreExistingBackup is true iff the BACKUP schedule should still be created even if a backup is already present in its destination. | no | +| `ApplicationName` | The application name for the session where recovery event was created. | no | +| `NumRows` | NumRows is the number of rows successfully imported, backed up or restored. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `sampled_exec_stats` + +An event of type `sampled_exec_stats` contains execution statistics that apply to both statements +and transactions. These stats as a whole are collected using a sampling approach. +These exec stats are meant to contain the same fields as ExecStats in +apps_stats.proto but are for a single execution rather than aggregated executions. +Fields in this struct should be updated in sync with apps_stats.proto. + + +| Field | Description | Sensitive | +|--|--|--| +| `NetworkBytes` | NetworkBytes collects the number of bytes sent over the network by DistSQL components. | no | +| `MaxMemUsage` | MaxMemUsage collects the maximum memory usage that occurred on a node. | no | +| `ContentionTime` | ContentionTime collects the time in seconds statements in the transaction spent contending. | no | +| `NetworkMessages` | NetworkMessages collects the number of messages that were sent over the network by DistSQL components. | no | +| `MaxDiskUsage` | MaxDiskUsage collects the maximum temporary disk usage that occurred. This is set in cases where a query had to spill to disk, e.g. when performing a large sort where not all of the tuples fit in memory. | no | +| `CPUSQLNanos` | CPUSQLNanos collects the CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `MVCCIteratorStats` | Internal storage iteration statistics. | yes | + + + +### `sampled_query` + +An event of type `sampled_query` is the SQL query event logged to the telemetry channel. It +contains common SQL event/execution details. + +Note: in version 26.1, these events will be moved to the `SQL_EXEC` channel. +To test compatability before this, set the cluster setting +`log.channel_compatibility_mode.enabled` to false. This will send the +events to `SQL_EXEC` instead of `TELEMETRY`. + + +| Field | Description | Sensitive | +|--|--|--| +| `SkippedQueries` | skipped_queries indicate how many SQL statements were not considered for sampling prior to this one. If the field is omitted, or its value is zero, this indicates that no statement was omitted since the last event. | no | +| `CostEstimate` | Cost of the query as estimated by the optimizer. | no | +| `Distribution` | The distribution of the DistSQL query plan (local, full, or partial). | no | +| `PlanGist` | The query's plan gist bytes as a base64 encoded string. | no | +| `SessionID` | SessionID is the ID of the session that initiated the query. | no | +| `Database` | Name of the database that initiated the query. | no | +| `StatementID` | Statement ID of the query. | no | +| `TransactionID` | Transaction ID of the query. | no | +| `MaxFullScanRowsEstimate` | Maximum number of rows scanned by a full scan, as estimated by the optimizer. | no | +| `TotalScanRowsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer. | no | +| `OutputRowsEstimate` | The number of rows output by the query, as estimated by the optimizer. | no | +| `StatsAvailable` | Whether table statistics were available to the optimizer when planning the query. | no | +| `NanosSinceStatsCollected` | The maximum number of nanoseconds that have passed since stats were collected on any table scanned by this query. | no | +| `BytesRead` | The number of bytes read from disk. | no | +| `RowsRead` | The number of rows read from disk. | no | +| `RowsWritten` | The number of rows written. | no | +| `InnerJoinCount` | The number of inner joins in the query plan. | no | +| `LeftOuterJoinCount` | The number of left (or right) outer joins in the query plan. | no | +| `FullOuterJoinCount` | The number of full outer joins in the query plan. | no | +| `SemiJoinCount` | The number of semi joins in the query plan. | no | +| `AntiJoinCount` | The number of anti joins in the query plan. | no | +| `IntersectAllJoinCount` | The number of intersect all joins in the query plan. | no | +| `ExceptAllJoinCount` | The number of except all joins in the query plan. | no | +| `HashJoinCount` | The number of hash joins in the query plan. | no | +| `CrossJoinCount` | The number of cross joins in the query plan. | no | +| `IndexJoinCount` | The number of index joins in the query plan. | no | +| `LookupJoinCount` | The number of lookup joins in the query plan. | no | +| `MergeJoinCount` | The number of merge joins in the query plan. | no | +| `InvertedJoinCount` | The number of inverted joins in the query plan. | no | +| `ApplyJoinCount` | The number of apply joins in the query plan. | no | +| `ZigZagJoinCount` | The number of zig zag joins in the query plan. | no | +| `ContentionNanos` | The duration of time in nanoseconds that the query experienced contention. | no | +| `Regions` | The regions of the nodes where SQL processors ran. | no | +| `NetworkBytesSent` | The number of network bytes by DistSQL components. | no | +| `MaxMemUsage` | The maximum amount of memory usage by nodes for this query. | no | +| `MaxDiskUsage` | The maximum amount of disk usage by nodes for this query. | no | +| `KVBytesRead` | The number of bytes read at the KV layer for this query. | no | +| `KVPairsRead` | The number of key-value pairs read at the KV layer for this query. | no | +| `KVRowsRead` | The number of rows read at the KV layer for this query. | no | +| `NetworkMessages` | The number of network messages sent by nodes for this query by DistSQL components. | no | +| `IndexRecommendations` | Generated index recommendations for this query. | no | +| `ScanCount` | The number of scans in the query plan. | no | +| `ScanWithStatsCount` | The number of scans using statistics (including forecasted statistics) in the query plan. | no | +| `ScanWithStatsForecastCount` | The number of scans using forecasted statistics in the query plan. | no | +| `TotalScanRowsWithoutForecastsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer without using forecasts. | no | +| `NanosSinceStatsForecasted` | The greatest quantity of nanoseconds that have passed since the forecast time (or until the forecast time, if it is in the future, in which case it will be negative) for any table with forecasted stats scanned by this query. | no | +| `Indexes` | The list of indexes used by this query. | no | +| `CpuTimeNanos` | Collects the cumulative CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `KvGrpcCalls` | The number of grpc calls done to get data form KV nodes | no | +| `KvTimeNanos` | Cumulated time spent waiting for a KV request. This includes disk IO time and potentially network time (if any of the keys are not local). | no | +| `ServiceLatencyNanos` | The time to service the query, from start of parse to end of execute. | no | +| `OverheadLatencyNanos` | The difference between service latency and the sum of parse latency + plan latency + run latency . | no | +| `RunLatencyNanos` | The time to run the query and fetch or compute the result rows. | no | +| `PlanLatencyNanos` | The time to transform the AST into a logical query plan. | no | +| `IdleLatencyNanos` | The time between statement executions in a transaction | no | +| `ParseLatencyNanos` | The time to transform the SQL string into an abstract syntax tree (AST). | no | +| `MvccStepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccStepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccBlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `MvccBlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `MvccKeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `SchemaChangerMode` | SchemaChangerMode is the mode that was used to execute the schema change, if any. | no | +| `SQLInstanceIDs` | SQLInstanceIDs is a list of all the SQL instances used in this statement's execution. | no | +| `KVNodeIDs` | KVNodeIDs is a list of all the KV nodes used in this statement's execution. | no | +| `StatementFingerprintID` | Statement fingerprint ID of the query. | no | +| `UsedFollowerRead` | UsedFollowerRead indicates whether at least some reads were served by the follower replicas. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sampled_transaction` + +An event of type `sampled_transaction` is the event logged to telemetry at the end of transaction execution. + +Note: in version 26.1, these events will be moved to the `SQL_EXEC` channel. +To test compatability before this, set the cluster setting +`log.channel_compatibility_mode.enabled` to false. This will send the +events to `SQL_EXEC` instead of `TELEMETRY`. + + +| Field | Description | Sensitive | +|--|--|--| +| `User` | User is the user account that triggered the transaction. The special usernames `root` and `node` are not considered sensitive. | depends | +| `ApplicationName` | ApplicationName is the application name for the session where the transaction was executed. This is included in the event to ease filtering of logging output by application. | no | +| `TxnCounter` | TxnCounter is the sequence number of the SQL transaction inside its session. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `TransactionID` | TransactionID is the id of the transaction. | no | +| `Committed` | Committed indicates if the transaction committed successfully. We want to include this value even if it is false. | no | +| `ImplicitTxn` | ImplicitTxn indicates if the transaction was an implicit one. We want to include this value even if it is false. | no | +| `StartTimeUnixNanos` | StartTimeUnixNanos is the time the transaction was started. Expressed as unix time in nanoseconds. | no | +| `EndTimeUnixNanos` | EndTimeUnixNanos the time the transaction finished (either committed or aborted). Expressed as unix time in nanoseconds. | no | +| `ServiceLatNanos` | ServiceLatNanos is the time to service the whole transaction, from start to end of execution. | no | +| `SQLSTATE` | SQLSTATE is the SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | ErrorText is the text of the error if any. | partially | +| `NumRetries` | NumRetries is the number of time when the txn was retried automatically by the server. | no | +| `LastAutoRetryReason` | LastAutoRetryReason is a string containing the reason for the last automatic retry. | partially | +| `NumRows` | NumRows is the total number of rows returned across all statements. | no | +| `RetryLatNanos` | RetryLatNanos is the amount of time spent retrying the transaction. | no | +| `CommitLatNanos` | CommitLatNanos is the amount of time spent committing the transaction after all statement operations. | no | +| `IdleLatNanos` | IdleLatNanos is the amount of time spent waiting for the client to send statements while the transaction is open. | no | +| `BytesRead` | BytesRead is the number of bytes read from disk. | no | +| `RowsRead` | RowsRead is the number of rows read from disk. | no | +| `RowsWritten` | RowsWritten is the number of rows written to disk. | no | +| `SampledExecStats` | SampledExecStats is a nested field containing execution statistics. This field will be omitted if the stats were not sampled. | yes | +| `SkippedTransactions` | SkippedTransactions is the number of transactions that were skipped as part of sampling prior to this one. We only count skipped transactions when telemetry logging is enabled and the sampling mode is set to "transaction". | no | +| `TransactionFingerprintID` | TransactionFingerprintID is the fingerprint ID of the transaction. This can be used to find the transaction in the console. | no | +| `StatementFingerprintIDs` | StatementFingerprintIDs is an array of statement fingerprint IDs belonging to this transaction. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_descriptor` + +An event of type `schema_descriptor` is an event for schema telemetry, whose purpose is +to take periodic snapshots of the cluster's SQL schema and publish them in +the telemetry log channel. For all intents and purposes, the data in such a +snapshot can be thought of the outer join of certain system tables: +namespace, descriptor, and at some point perhaps zones, etc. + +Snapshots are too large to conveniently be published as a single log event, +so instead they're broken down into SchemaDescriptor events which +contain the data in one record of this outer join projection. These events +are prefixed by a header (a SchemaSnapshotMetadata event). + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of the snapshot that this event is part of. | no | +| `ParentDatabaseID` | ParentDatabaseID matches the same key column in system.namespace. | no | +| `ParentSchemaID` | ParentSchemaID matches the same key column in system.namespace. | no | +| `Name` | Name matches the same key column in system.namespace. | no | +| `DescID` | DescID matches the 'id' column in system.namespace and system.descriptor. | no | +| `Desc` | Desc matches the 'descriptor' column in system.descriptor. Some contents of the descriptor may be redacted to prevent leaking PII. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_snapshot_metadata` + +An event of type `schema_snapshot_metadata` is an event describing a schema snapshot, which +is a set of SchemaDescriptor messages sharing the same SnapshotID. + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of this snapshot. | no | +| `NumRecords` | NumRecords is how many SchemaDescriptor events are in the snapshot. | no | +| `AsOfTimestamp` | AsOfTimestamp is when the snapshot was taken. This is equivalent to the timestamp given in the AS OF SYSTEM TIME clause when querying the namespace and descriptor tables in the system database. Expressed as nanoseconds since the Unix epoch. | no | +| `Errors` | Errors records any errors encountered when post-processing this snapshot, which includes the redaction of any potential PII. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Zone config events + +Events in this category pertain to zone configuration changes on +the SQL schema or system ranges. + +When zone configs apply to individual tables or other objects in a +SQL logical schema, they are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these zone config events are preserved +in each tenant's own `system.eventlog` table. + +When they apply to cluster-level ranges (e.g., the system zone config), +they are stored in the system tenant's own `system.eventlog` table. + +Events in this category are logged to the `OPS` channel. + + +### `remove_zone_config` + +An event of type `remove_zone_config` is recorded when a zone config is removed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `set_zone_config` + +An event of type `set_zone_config` is recorded when a zone config is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `ResolvedOldConfig` | The string representation of the resolved old zone config. This is not necessarily the same as the zone config that was previously set -- as it includes the resolved values of the zone config options. In other words, a zone config that hasn't been properly "set" yet (and inherits from its parent) will have a resolved_old_config that has details of the values it inherits from its parent. This is particularly useful to get a proper diff between the old and new zone config. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + + + + +## Enumeration types + +### `AuthFailReason` + +AuthFailReason is the inventory of possible reasons for an +authentication failure. + + +| Value | Textual alias in code or documentation | Description | +|--|--|--| +| 0 | UNKNOWN | is reported when the reason is unknown. | +| 1 | USER_RETRIEVAL_ERROR | occurs when there was an internal error accessing the principals. | +| 2 | USER_NOT_FOUND | occurs when the principal is unknown. | +| 3 | LOGIN_DISABLED | occurs when the user does not have LOGIN privileges. | +| 4 | METHOD_NOT_FOUND | occurs when no HBA rule matches or the method does not exist. | +| 5 | PRE_HOOK_ERROR | occurs when the authentication handshake encountered a protocol error. | +| 6 | CREDENTIALS_INVALID | occurs when the client-provided credentials were invalid. | +| 7 | CREDENTIALS_EXPIRED | occur when the credentials provided by the client are expired. | +| 8 | NO_REPLICATION_ROLEOPTION | occurs when the connection requires a replication role option, but the user does not have it. | +| 9 | AUTHORIZATION_ERROR | is used for errors during the authorization phase. For example, this would include issues with mapping LDAP groups to SQL roles and granting those roles to the user. | +| 10 | PROVISIONING_ERROR | is used for errors during the user provisioning phase. This would include errors when the transaction to provision the authenticating user failed to execute. | + + + diff --git a/src/current/_includes/cockroach-generated/release-25.4/logformats.md b/src/current/_includes/cockroach-generated/release-25.4/logformats.md new file mode 100644 index 00000000000..89580c9fc15 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.4/logformats.md @@ -0,0 +1,382 @@ + +The supported log output formats are documented below. + + +- [`crdb-v1`](#format-crdb-v1) + +- [`crdb-v1-count`](#format-crdb-v1-count) + +- [`crdb-v1-tty`](#format-crdb-v1-tty) + +- [`crdb-v1-tty-count`](#format-crdb-v1-tty-count) + +- [`crdb-v2`](#format-crdb-v2) + +- [`crdb-v2-tty`](#format-crdb-v2-tty) + +- [`json`](#format-json) + +- [`json-compact`](#format-json-compact) + +- [`json-fluent`](#format-json-fluent) + +- [`json-fluent-compact`](#format-json-fluent-compact) + + + +## Format `crdb-v1` + + +This is a legacy file format used from CockroachDB v1.0. + +Each log entry is emitted using a common prefix, described below, followed by: + +- The logging context tags enclosed between `[` and `]`, if any. It is possible + for this to be omitted if there were no context tags. +- Optionally, a counter column, if the option 'show-counter' is enabled. See below for details. +- the text of the log entry. + +Beware that the text of the log entry can span multiple lines. +The following caveats apply: + +- The text of the log entry can start with text enclosed between `[` and `]`. + If there were no logging tags to start with, it is not possible to distinguish between + logging context tag information and a `[...]` string in the main text of the + log entry. This means that this format is ambiguous. + + To remove this ambiguity, you can use the option 'show-counter'. + +- The text of the log entry can embed arbitrary application-level strings, + including strings that represent log entries. In particular, an accident + of implementation can cause the common entry prefix (described below) + to also appear on a line of its own, as part of the payload of a previous + log entry. There is no automated way to recognize when this occurs. + Care must be taken by a human observer to recognize these situations. + +- The log entry parser provided by CockroachDB to read log files is faulty + and is unable to recognize the aforementioned pitfall; nor can it read + entries larger than 64KiB successfully. Generally, use of this internal + log entry parser is discouraged for entries written with this format. + +See the newer format `crdb-v2` for an alternative +without these limitations. + +### Header lines + +At the beginning of each file, a header is printed using a similar format as +regular log entries. This header reports when the file was created, +which parameters were used to start the server, the server identifiers +if known, and other metadata about the running process. + +- This header appears to be logged at severity `INFO` (with an `I` prefix + at the start of the line) even though it does not really have a severity. +- The header is printed unconditionally even when a filter is configured to + omit entries at the `INFO` level. + +### Common log entry prefix + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker tags counter + +Reminder, the tags may be omitted; and the counter is only printed if the option +'show-counter' is specified. + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (omitted if zero for use by tests). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. | +| line | The line number where the entry originated. | +| marker | Redactability marker ` + redactableIndicator + ` (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. May be absent. | +| counter | The entry counter. Only included if 'show-counter' is enabled. | + +The redactability marker can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. + +If the marker ` + redactableIndicator + ` is present, the remainder of the log entry +contains delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `show-counter` | Whether to include the counter column in the line header. Without it, the format may be ambiguous due to the optionality of tags. | +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v1-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: none` + + +## Format `crdb-v1-tty` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: false` +- `colors: auto` + + +## Format `crdb-v1-tty-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: auto` + + +## Format `crdb-v2` + +This is the main file format used from CockroachDB v21.1. + +Each log entry is emitted using a common prefix, described below, +followed by the text of the log entry. + +### Entry format + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker [tags...] counter cont + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (zero when cannot be determined). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. Also see below. | +| line | The line number where the entry originated. | +| marker | Redactability marker "⋮" (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. See below. | +| counter | The optional entry counter (see below for details). | +| cont | Continuation mark for structured and multi-line entries. See below. | + +The `chan@` prefix before the file name indicates the logging channel, +and is omitted if the channel is `DEV`. + +The file name may be prefixed by the string `(gostd) ` to indicate +that the log entry was produced inside the Go standard library, instead +of a CockroachDB component. Entry parsers must be configured to ignore this prefix +when present. + +`marker` can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. +If the marker "⋮" is present, the remainder of the log entry +contains delimiters (‹...›) +around fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +when log redaction is requested. + +The logging `tags` are enclosed between square brackets `[...]`, +and the syntax `[-]` is used when there are no logging tags +associated with the log entry. + +`counter` is numeric, and is incremented for every +log entry emitted to this sink. (There is thus one counter sequence per +sink.) For entries that do not have a counter value +associated (e.g., header entries in file sinks), the counter position +in the common prefix is empty: `tags` is then +followed by two ASCII space characters, instead of one space; the `counter`, +and another space. The presence of the two ASCII spaces indicates +reliably that no counter was present. + +`cont` is a format/continuation indicator: + +| Continuation indicator | ASCII | Description | +|------------------------|-------|--| +| space | 0x32 | Start of an unstructured entry. | +| equal sign, "=" | 0x3d | Start of a structured entry. | +| exclamation mark, "!" | 0x21 | Start of an embedded stack trace. | +| plus sign, "+" | 0x2b | Continuation of a multi-line entry. The payload contains a newline character at this position. | +| vertical bar | 0x7c | Continuation of a large entry. | + +### Examples + +Example single-line unstructured entry: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 started with engine type ‹2› +~~~ + +Example multi-line unstructured entry: + +~~~ +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 node startup completed: +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 +CockroachDB node starting at 2021-01-16 21:49 (took 0.0s) +~~~ + +Example structured entry: + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventType":"node_restart"} +~~~ + +Example long entries broken up into multiple lines: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.... +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 |aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +~~~ + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventTy... +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 |pe":"node_restart"} +~~~ + +### Backward-compatibility notes + +Entries in this format can be read by most `crdb-v1` log parsers, +in particular the one included in the DB console and +also the [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +facility. + +However, implementers of previous version parsers must +understand that the logging tags field is now always +included, and the lack of logging tags is included +by a tag string set to `[-]`. + +Likewise, the entry counter is now also always included, +and there is a special character after `counter` +to indicate whether the remainder of the line is a +structured entry, or a continuation of a previous entry. + +Finally, in the previous format, structured entries +were prefixed with the string `Structured entry: `. In +the new format, they are prefixed by the `=` continuation +indicator. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v2-tty` + +This format name is an alias for 'crdb-v2' with +the following format option defaults: + +- `colors: auto` + + +## Format `json` + +This format emits log entries as a JSON payload. + +The JSON object is guaranteed to not contain unescaped newlines +or other special characters, and the entry as a whole is followed +by a newline character. This makes the format suitable for +processing over a stream unambiguously. + +Each entry contains at least the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `tag` | `tag` | (Only if the option `fluent-tag: true` is given.) A Fluent tag for the event, formed by the process name and the logging channel. | +| `d` | `datetime` | The pretty-printed date/time of the event timestamp, if enabled via options. | +| `f` | `file` | The name of the source file where the event was emitted. | +| `g` | `goroutine` | The identifier of the goroutine where the event was emitted. | +| `l` | `line` | The line number where the event was emitted in the source. | +| `r` | `redactable` | Whether the payload is redactable (see below for details). | +| `t` | `timestamp` | The timestamp at which the event was emitted on the logging channel. | +| `v` | `version` | The binary version with which the event was generated. | + + +After a couple of *header* entries written at the beginning of each log sink, +all subsequent log entries also contain the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `C` | `channel` | The name of the logging channel where the event was sent. | +| `sev` | `severity` | The severity of the event. | +| `c` | `channel_numeric` | The numeric identifier for the logging channel where the event was sent. | +| `n` | `entry_counter` | The entry number on this logging sink, relative to the last process restart. | +| `s` | `severity_numeric` | The numeric value of the severity of the event. | + + +Additionally, the following fields are conditionally present: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `N` | `node_id` | The node ID where the event was generated, once known. Only reported for single-tenant or KV servers. | +| `x` | `cluster_id` | The cluster ID where the event was generated, once known. Only reported for single-tenant of KV servers. | +| `q` | `instance_id` | The SQL instance ID where the event was generated, once known. | +| `T` | `tenant_id` | The SQL tenant ID where the event was generated, once known. | +| `V` | `tenant_name` | The SQL virtual cluster where the event was generated, once known. | +| `tags` | `tags` | The logging context tags for the entry, if there were context tags. | +| `message` | `message` | For unstructured events, the flat text payload. | +| `event` | `event` | The logging event, if structured (see below for details). | +| `stacks` | `stacks` | Goroutine stacks, for fatal events. | + +When an entry is structured, the `event` field maps to a dictionary +whose structure is one of the documented structured events. See the [reference documentation](eventlog.html) +for structured events for a list of possible payloads. + +When the entry is marked as `redactable`, the `tags`, `message`, and/or `event` payloads +contain delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `datetime-format` | The format to use for the `datetime` field. The value can be one of `none`, `iso8601`/`rfc3339` (synonyms), or `rfc1123`. Default is `none`. | +| `datetime-timezone` | The timezone to use for the `datetime` field. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | +| `tag-style` | The tags to include in the envelope. The value can be `compact` (one letter tags) or `verbose` (long-form tags). Default is `verbose`. | +| `fluent-tag` | Whether to produce an additional field called `tag` for Fluent compatibility. Default is `false`. | + + + +## Format `json-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: false` +- `tag-style: compact` + + +## Format `json-fluent` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: verbose` + + +## Format `json-fluent-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: compact` + + diff --git a/src/current/_includes/cockroach-generated/release-25.4/logging.md b/src/current/_includes/cockroach-generated/release-25.4/logging.md new file mode 100644 index 00000000000..7661187987e --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.4/logging.md @@ -0,0 +1,188 @@ +## Logging levels (severities) + +### INFO + +The `INFO` severity is used for informational messages that do not +require action. + +### WARNING + +The `WARNING` severity is used for situations which may require special handling, +where normal operation is expected to resume automatically. + +### ERROR + +The `ERROR` severity is used for situations that require special handling, +where normal operation could not proceed as expected. +Other operations can continue mostly unaffected. + +### FATAL + +The `FATAL` severity is used for situations that require an immedate, hard +server shutdown. A report is also sent to telemetry if telemetry +is enabled. + + +## Logging channels + +### `DEV` + +The `DEV` channel is used during development to collect log +details useful for troubleshooting that fall outside the +scope of other channels. It is also the default logging +channel for events not associated with a channel. + +This channel is special in that there are no constraints as to +what may or may not be logged on it. Conversely, users in +production deployments are invited to not collect `DEV` logs in +centralized logging facilities, because they likely contain +sensitive operational data. +See [Configure logs](configure-logs.html#dev-channel). + +### `OPS` + +The `OPS` channel is used to report "point" operational events, +initiated by user operators or automation: + + - Operator or system actions on server processes: process starts, + stops, shutdowns, crashes (if they can be logged), + including each time: command-line parameters, current version being run + - Actions that impact the topology of a cluster: node additions, + removals, decommissions, etc. + - Job-related initiation or termination + - [Cluster setting](cluster-settings.html) changes + - [Zone configuration](configure-replication-zones.html) changes + +### `HEALTH` + +The `HEALTH` channel is used to report "background" operational +events, initiated by CockroachDB or reporting on automatic processes: + + - Current resource usage, including critical resource usage + - Node-node connection events, including connection errors and + gossip details + - Range and table leasing events + - Up- and down-replication, range unavailability + +### `STORAGE` + +The `STORAGE` channel is used to report low-level storage +layer events (RocksDB/Pebble). + +### `SESSIONS` + +The `SESSIONS` channel is used to report client network activity when enabled via +the `server.auth_log.sql_connections.enabled` and/or +`server.auth_log.sql_sessions.enabled` [cluster setting](cluster-settings.html): + + - Connections opened/closed + - Authentication events: logins, failed attempts + - Session and query cancellation + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_SCHEMA` + +The `SQL_SCHEMA` channel is used to report changes to the +SQL logical schema, excluding privilege and ownership changes +(which are reported separately on the `PRIVILEGES` channel) and +zone configuration changes (which go to the `OPS` channel). + +This includes: + + - Database/schema/table/sequence/view/type creation + - Adding/removing/changing table columns + - Changing sequence parameters + +`SQL_SCHEMA` events generally comprise changes to the schema that affect the +functional behavior of client apps using stored objects. + +### `USER_ADMIN` + +The `USER_ADMIN` channel is used to report changes +in users and roles, including: + + - Users added/dropped + - Changes to authentication credentials (e.g., passwords, validity, etc.) + - Role grants/revocations + - Role option grants/revocations + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `PRIVILEGES` + +The `PRIVILEGES` channel is used to report data +authorization changes, including: + + - Privilege grants/revocations on database, objects, etc. + - Object ownership changes + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SENSITIVE_ACCESS` + +The `SENSITIVE_ACCESS` channel is used to report SQL +data access to sensitive data: + + - Data access audit events (when table audit is enabled via + [ALTER TABLE ... EXPERIMENTAL_AUDIT](alter-table.html#experimental_audit)) + - Data access audit events (when role-based audit is enabled via + [`sql.log.user_audit` cluster setting](role-based-audit-logging.html#syntax-of-audit-settings)) + - SQL statements executed by users with the admin role + - Operations that write to system tables + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_EXEC` + +The `SQL_EXEC` channel is used to report SQL execution on +behalf of client connections: + + - Logical SQL statement executions (when enabled via the + `sql.log.all_statements.enabled` [cluster setting](cluster-settings.html)) + - uncaught Go panic errors during the execution of a SQL statement. + +### `SQL_PERF` + +The `SQL_PERF` channel is used to report SQL executions +that are marked as "out of the ordinary" +to facilitate performance investigations. +This includes the SQL "slow query log". + +Arguably, this channel overlaps with `SQL_EXEC`. +However, we keep both channels separate for backward compatibility +with versions prior to v21.1, where the corresponding events +were redirected to separate files. + +### `SQL_INTERNAL_PERF` + +The `SQL_INTERNAL_PERF` channel is like the `SQL_PERF` channel, but is aimed at +helping developers of CockroachDB itself. It exists as a separate +channel so as to not pollute the `SQL_PERF` logging output with +internal troubleshooting details. + +### `TELEMETRY` + +The `TELEMETRY` channel reports telemetry events. Telemetry events describe +feature usage within CockroachDB and anonymizes any application- +specific data. + +### `KV_DISTRIBUTION` + +The `KV_DISTRIBUTION` channel is used to report data distribution events, such as moving +replicas between stores in the cluster, or adding (removing) replicas to +ranges. + +### `CHANGEFEED` + +The `CHANGEFEED` channel is used to report changefeed events + +### `KV_EXEC` + +The `KV_EXEC` channel is used to report KV execution events that don't fall into the +KV_DISTRIBUTION channel. + diff --git a/src/current/_includes/cockroach-generated/release-25.4/settings/settings.html b/src/current/_includes/cockroach-generated/release-25.4/settings/settings.html new file mode 100644 index 00000000000..1a61f0cfbfe --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.4/settings/settings.html @@ -0,0 +1,391 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingTypeDefaultDescriptionSupported Deployments
admission.disk_bandwidth_tokens.elastic.enabled
booleantruewhen true, and provisioned bandwidth for the disk corresponding to a store is configured, tokens for elastic work will be limited if disk bandwidth becomes a bottleneckAdvanced/Self-Hosted
admission.epoch_lifo.enabled
booleanfalsewhen true, epoch-LIFO behavior is enabled when there is significant delay in admissionBasic/Standard/Advanced/Self-Hosted
admission.epoch_lifo.epoch_closing_delta_duration
duration5msthe delta duration before closing an epoch, for epoch-LIFO admission control orderingBasic/Standard/Advanced/Self-Hosted
admission.epoch_lifo.epoch_duration
duration100msthe duration of an epoch, for epoch-LIFO admission control orderingBasic/Standard/Advanced/Self-Hosted
admission.epoch_lifo.queue_delay_threshold_to_switch_to_lifo
duration105msthe queue delay encountered by a (tenant,priority) for switching to epoch-LIFO orderingBasic/Standard/Advanced/Self-Hosted
admission.kv.enabled
booleantruewhen true, work performed by the KV layer is subject to admission controlAdvanced/Self-Hosted
admission.sql_kv_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a KV response is subject to admission controlBasic/Standard/Advanced/Self-Hosted
admission.sql_sql_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a DistSQL response is subject to admission controlBasic/Standard/Advanced/Self-Hosted
bulkio.backup.file_size
byte size128 MiBtarget size for individual data files produced during BACKUPBasic/Standard/Advanced/Self-Hosted
bulkio.backup.read_timeout
duration5m0samount of time after which a read attempt is considered timed out, which causes the backup to failBasic/Standard/Advanced/Self-Hosted
bulkio.backup.read_with_priority_after
duration1m0samount of time since the read-as-of time above which a BACKUP should use priority when retrying readsBasic/Standard/Advanced/Self-Hosted
physical_replication.consumer.minimum_flush_interval
(alias: bulkio.stream_ingestion.minimum_flush_interval)
duration5sthe minimum timestamp between flushes; flushes may still occur if internal buffers fill upAdvanced/Self-Hosted
changefeed.aggregator.flush_jitter
float0.1jitter aggregator flushes as a fraction of min_checkpoint_frequency. This setting has no effect if min_checkpoint_frequency is set to 0.Basic/Standard/Advanced/Self-Hosted
changefeed.backfill.concurrent_scan_requests
integer0number of concurrent scan requests per node issued during a backfillBasic/Standard/Advanced/Self-Hosted
changefeed.backfill.scan_request_size
integer524288the maximum number of bytes returned by each scan requestBasic/Standard/Advanced/Self-Hosted
changefeed.batch_reduction_retry.enabled
(alias: changefeed.batch_reduction_retry_enabled)
booleanfalseif true, kafka changefeeds upon erroring on an oversized batch will attempt to resend the messages with progressively lower batch sizesBasic/Standard/Advanced/Self-Hosted
changefeed.default_range_distribution_strategy
enumerationdefaultconfigures how work is distributed among nodes for a given changefeed. for the most balanced distribution, use `balanced_simple`. changing this setting will not override locality restrictions [default = 0, balanced_simple = 1]Basic/Standard/Advanced/Self-Hosted
changefeed.event_consumer_worker_queue_size
integer16if changefeed.event_consumer_workers is enabled, this setting sets the maxmimum number of events which a worker can bufferBasic/Standard/Advanced/Self-Hosted
changefeed.event_consumer_workers
integer0the number of workers to use when processing events: <0 disables, 0 assigns a reasonable default, >0 assigns the setting value. for experimental/core changefeeds and changefeeds using parquet format, this is disabledBasic/Standard/Advanced/Self-Hosted
changefeed.fast_gzip.enabled
booleantrueuse fast gzip implementationBasic/Standard/Advanced/Self-Hosted
changefeed.span_checkpoint.lag_threshold
(alias: changefeed.frontier_highwater_lag_checkpoint_threshold)
duration10m0sthe amount of time a changefeed's lagging (slowest) spans must lag behind its leading (fastest) spans before a span-level checkpoint to save leading span progress is written; if 0, span-level checkpoints due to lagging spans is disabledBasic/Standard/Advanced/Self-Hosted
changefeed.kafka.max_request_size
byte size256 MiBthe maximum number of uncompressed bytes sent in a single request to a Kafka broker; lowering this value helps avoid spurious "message too large" errors that can occur when multiple messages are combined into a single batch; this setting is overridden by the per-changefeed Flush { MaxBytes: <int> } optionBasic/Standard/Advanced/Self-Hosted
changefeed.kafka_v2_error_details.enabled
booleantrueif enabled, Kafka v2 sinks will include the message key, size, and MVCC timestamp in message too large errorsBasic/Standard/Advanced/Self-Hosted
changefeed.memory.per_changefeed_limit
byte size512 MiBcontrols amount of data that can be buffered per changefeedBasic/Standard/Advanced/Self-Hosted
changefeed.resolved_timestamp.min_update_interval
(alias: changefeed.min_highwater_advance)
duration0sminimum amount of time that must have elapsed since the last time a changefeed's resolved timestamp was updated before it is eligible to be updated again; default of 0 means no minimum interval is enforced but updating will still be limited by the average time it takes to checkpoint progressBasic/Standard/Advanced/Self-Hosted
changefeed.node_throttle_config
stringspecifies node level throttling configuration for all changefeeedsBasic/Standard/Advanced/Self-Hosted
changefeed.partition_alg.enabled
booleanfalseif enabled, allows specifying the partition_alg changefeed option to choose between fnv-1a (default) and murmur2 hash functions for Kafka partitioning. Only affects changefeeds using a kafka sink with changefeed.new_kafka_sink_enabled set to true.Basic/Standard/Advanced/Self-Hosted
changefeed.progress.frontier_persistence.interval
duration30sminimum amount of time that must elapse before a changefeed will persist its entire span frontier againBasic/Standard/Advanced/Self-Hosted
changefeed.protect_timestamp.max_age
duration96h0m0sfail the changefeed if the protected timestamp age exceeds this threshold; 0 disables expirationBasic/Standard/Advanced/Self-Hosted
changefeed.protect_timestamp_interval
duration10m0scontrols how often the changefeed forwards its protected timestamp to the resolved timestampBasic/Standard/Advanced/Self-Hosted
changefeed.schema_feed.read_with_priority_after
duration1m0sretry with high priority if we were not able to read descriptors for too long; 0 disablesBasic/Standard/Advanced/Self-Hosted
changefeed.sink_io_workers
integer0the number of workers used by changefeeds when sending requests to the sink (currently the batching versions of webhook, pubsub, and kafka sinks that are enabled by changefeed.new_<sink type>_sink_enabled only): <0 disables, 0 assigns a reasonable default, >0 assigns the setting valueBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.concurrent_upload_buffers
integer1controls the number of concurrent buffers that will be used by the Azure client when uploading chunks.Each buffer can buffer up to cloudstorage.write_chunk.size of memory during an uploadBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.gs.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.gs.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.gs.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.gs.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.custom_ca
stringcustom root CA (appended to system's default CAs) for verifying certificates when interacting with HTTPS storageBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nodelocal.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nodelocal.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nodelocal.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nodelocal.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nullsink.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nullsink.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nullsink.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nullsink.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.s3.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.s3.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.s3.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.s3.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.timeout
duration10m0sthe timeout for import/export storage operationsBasic/Standard/Advanced/Self-Hosted
cloudstorage.userfile.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.userfile.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.userfile.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.userfile.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cluster.auto_upgrade.enabled
booleantruedisable automatic cluster version upgrade until resetBasic/Standard/Advanced/Self-Hosted
cluster.organization
stringorganization nameAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
cluster.preserve_downgrade_option
stringdisable (automatic or manual) cluster version upgrade from the specified version until resetBasic/Standard/Advanced/Self-Hosted
debug.zip.redact_addresses.enabled
booleanfalseenables the redaction of hostnames and ip addresses in debug zipBasic/Standard/Advanced/Self-Hosted
diagnostics.active_query_dumps.enabled
booleantrueexperimental: enable dumping of anonymized active queries to disk when node is under memory pressureAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
diagnostics.forced_sql_stat_reset.interval
duration2h0m0sinterval after which the reported SQL Stats are reset even if not collected by telemetry reporter. It has a max value of 24H.Basic/Standard/Advanced/Self-Hosted
diagnostics.memory_monitoring_dumps.enabled
booleantrueenable dumping of memory monitoring state at the same time as heap profiles are takenAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
diagnostics.reporting.enabled
booleantrueenable reporting diagnostic metrics to cockroach labs, but is ignored for Trial or Free licensesBasic/Standard/Advanced/Self-Hosted
diagnostics.reporting.interval
duration1h0m0sinterval at which diagnostics data should be reportedBasic/Standard/Advanced/Self-Hosted
enterprise.license
stringthe encoded cluster licenseAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
external.graphite.endpoint
stringif nonempty, push server metrics to the Graphite or Carbon server at the specified host:portBasic/Standard/Advanced/Self-Hosted
external.graphite.interval
duration10sthe interval at which metrics are pushed to Graphite (if enabled)Basic/Standard/Advanced/Self-Hosted
feature.backup.enabled
booleantrueset to true to enable backups, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.changefeed.enabled
booleantrueset to true to enable changefeeds, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.export.enabled
booleantrueset to true to enable exports, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.import.enabled
booleantrueset to true to enable imports, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.infer_rbr_region_col_using_constraint.enabled
booleanfalseset to true to enable looking up the region column via a foreign key constraint in a REGIONAL BY ROW table, false to disable; default is falseBasic/Standard/Advanced/Self-Hosted
feature.restore.enabled
booleantrueset to true to enable restore, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.schema_change.enabled
booleantrueset to true to enable schema changes, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.stats.enabled
booleantrueset to true to enable CREATE STATISTICS/ANALYZE, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.vector_index.enabled
booleantrueset to true to enable vector indexes, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
jobs.retention_time
duration336h0m0sthe amount of time for which records for completed jobs are retainedBasic/Standard/Advanced/Self-Hosted
kv.allocator.lease_rebalance_threshold
float0.05minimum fraction away from the mean a store's lease count can be before it is considered for lease-transfersAdvanced/Self-Hosted
kv.allocator.load_based_lease_rebalancing.enabled
booleantrueset to enable rebalancing of range leases based on load and latencyAdvanced/Self-Hosted
kv.allocator.load_based_rebalancing
enumerationleases and replicaswhether to rebalance based on the distribution of load across stores [off = 0, leases = 1, leases and replicas = 2, multi-metric only = 3, multi-metric and count = 4]Advanced/Self-Hosted
kv.allocator.load_based_rebalancing.objective
enumerationcpuwhat objective does the cluster use to rebalance; if set to `qps` the cluster will attempt to balance qps among stores, if set to `cpu` the cluster will attempt to balance cpu usage among stores [qps = 0, cpu = 1]Advanced/Self-Hosted
kv.allocator.load_based_rebalancing_interval
duration1m0sthe rough interval at which each store will check for load-based lease / replica rebalancing opportunitiesAdvanced/Self-Hosted
kv.allocator.qps_rebalance_threshold
float0.1minimum fraction away from the mean a store's QPS (such as queries per second) can be before it is considered overfull or underfullAdvanced/Self-Hosted
kv.allocator.range_rebalance_threshold
float0.05minimum fraction away from the mean a store's range count can be before it is considered overfull or underfullAdvanced/Self-Hosted
kv.allocator.store_cpu_rebalance_threshold
float0.1minimum fraction away from the mean a store's cpu usage can be before it is considered overfull or underfullAdvanced/Self-Hosted
kv.bulk_io_write.max_rate
byte size1.0 TiBthe rate limit (bytes/sec) to use for writes to disk on behalf of bulk io opsAdvanced/Self-Hosted
kv.bulk_io_write.min_capacity_remaining_fraction
float0.05remaining store capacity fraction below which bulk ingestion requests are rejectedAdvanced/Self-Hosted
kv.bulk_sst.max_allowed_overage
byte size64 MiBif positive, allowed size in excess of target size for SSTs from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryAdvanced/Self-Hosted
kv.bulk_sst.target_size
byte size16 MiBtarget size for SSTs emitted from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.follower_reads.enabled
(alias: kv.closed_timestamp.follower_reads_enabled)
booleantrueallow (all) replicas to serve consistent historical reads based on closed timestamp informationAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.lead_for_global_reads_auto_tune.enabled
booleanfalseif enabled, observed network latency between leaseholders and their furthest follower will be used to adjust closed timestamp policies for rangesranges configured to serve global reads. kv.closed_timestamp.lead_for_global_reads_override takes precedence if set.Advanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.lead_for_global_reads_override
duration0sif nonzero, overrides the lead time that global_read ranges use to publish closed timestampsAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.side_transport_interval
duration200msthe interval at which the closed timestamp side-transport attempts to advance each range's closed timestamp; set to 0 to disable the side-transportAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.target_duration
duration3sif nonzero, attempt to provide closed timestamp notifications for timestamps trailing cluster time by approximately this durationAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.dist_sender.circuit_breaker.cancellation.enabled
booleantruewhen enabled, in-flight requests will be cancelled when the circuit breaker tripsBasic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breaker.cancellation.write_grace_period
duration10show long after the circuit breaker trips to cancel write requests (these can't retry internally, so should be long enough to allow quorum/lease recovery)Basic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breaker.probe.interval
duration3sinterval between replica probesBasic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breaker.probe.threshold
duration3sduration of errors or stalls after which a replica will be probedBasic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breaker.probe.timeout
duration3stimeout for replica probesBasic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breakers.mode
enumerationliveness range onlyset of ranges to trip circuit breakers for failing or stalled replicas [no ranges = 0, liveness range only = 1, all ranges = 2]Basic/Standard/Advanced/Self-Hosted
kv.lease_transfer_read_summary.global_budget
byte size0 Bcontrols the maximum number of bytes that will be used to summarize the global segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Advanced/Self-Hosted
kv.lease_transfer_read_summary.local_budget
byte size4.0 MiBcontrols the maximum number of bytes that will be used to summarize the local segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Advanced/Self-Hosted
kv.log_range_and_node_events.enabled
booleantrueset to true to transactionally log range events (e.g., split, merge, add/remove voter/non-voter) into system.rangelogand node join and restart events into system.eventologAdvanced/Self-Hosted
kv.protectedts.reconciliation.interval
duration5m0sthe frequency for reconciling jobs with protected timestamp recordsAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.raft.leader_fortification.fraction_enabled
float1controls the fraction of ranges for which the raft leader fortification protocol is enabled. Leader fortification is needed for a range to use a Leader lease. Set to 0.0 to disable leader fortification and, by extension, Leader leases. Set to 1.0 to enable leader fortification for all ranges and, by extension, use Leader leases for all ranges which do not require expiration-based leases. Set to a value between 0.0 and 1.0 to gradually roll out Leader leases across the ranges in a cluster.Advanced/Self-Hosted
kv.range.range_size_hard_cap
byte size8.0 GiBhard cap on the maximum size a range is allowed to grow to withoutsplitting before writes to the range are blocked. Takes precedence over all other configurationsAdvanced/Self-Hosted
kv.range_split.by_load.enabled
(alias: kv.range_split.by_load_enabled)
booleantrueallow automatic splits of ranges based on where load is concentratedAdvanced/Self-Hosted
kv.range_split.load_cpu_threshold
duration500msthe CPU use per second over which, the range becomes a candidate for load based splittingAdvanced/Self-Hosted
kv.range_split.load_qps_threshold
integer2500the QPS over which, the range becomes a candidate for load based splittingAdvanced/Self-Hosted
kv.rangefeed.client.stream_startup_rate
integer100controls the rate per second the client will initiate new rangefeed stream for a single range; 0 implies unlimitedBasic/Standard/Advanced/Self-Hosted
kv.rangefeed.closed_timestamp_refresh_interval
duration3sthe interval at which closed-timestamp updatesare delivered to rangefeeds; set to 0 to use kv.closed_timestamp.side_transport_intervalAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.rangefeed.enabled
booleanfalseif set, rangefeed registration is enabledAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.replica_circuit_breaker.slow_replication_threshold
duration1m0sduration after which slow proposals trip the per-Replica circuit breaker (zero duration disables breakers)Advanced/Self-Hosted
kv.replica_raft.leaderless_unavailable_threshold
duration1m0sduration after which leaderless replicas is considered unavailable. Set to 0 to disable leaderless replica availability checksAdvanced/Self-Hosted
kv.replica_stats.addsst_request_size_factor
integer50000the divisor that is applied to addsstable request sizes, then recorded in a leaseholders QPS; 0 means all requests are treated as cost 1Advanced/Self-Hosted
kv.replication_reports.interval
duration1m0sthe frequency for generating the replication_constraint_stats, replication_stats_report and replication_critical_localities reports (set to 0 to disable)Advanced/Self-Hosted
kv.snapshot_rebalance.max_rate
byte size32 MiBthe rate limit (bytes/sec) to use for rebalance and upreplication snapshotsAdvanced/Self-Hosted
kv.transaction.max_intents_and_locks
integer0maximum count of inserts or durable locks for a single transactions, 0 to disableBasic/Standard/Advanced/Self-Hosted
kv.transaction.max_intents_bytes
integer4194304maximum number of bytes used to track locks in transactionsBasic/Standard/Advanced/Self-Hosted
kv.transaction.max_refresh_spans_bytes
integer4194304maximum number of bytes used to track refresh spans in serializable transactionsBasic/Standard/Advanced/Self-Hosted
kv.transaction.randomized_anchor_key.enabled
booleanfalsedictates whether a transactions anchor key is randomized or notBasic/Standard/Advanced/Self-Hosted
kv.transaction.reject_over_max_intents_budget.enabled
booleanfalseif set, transactions that exceed their lock tracking budget (kv.transaction.max_intents_bytes) are rejected instead of having their lock spans imprecisely compressedBasic/Standard/Advanced/Self-Hosted
kv.transaction.write_pipelining.locking_reads.enabled
booleantrueif enabled, transactional locking reads are pipelined through Raft consensusBasic/Standard/Advanced/Self-Hosted
kv.transaction.write_pipelining.ranged_writes.enabled
booleantrueif enabled, transactional ranged writes are pipelined through Raft consensusBasic/Standard/Advanced/Self-Hosted
kv.transaction.write_pipelining.enabled
(alias: kv.transaction.write_pipelining_enabled)
booleantrueif enabled, transactional writes are pipelined through Raft consensusBasic/Standard/Advanced/Self-Hosted
kv.transaction.write_pipelining.max_batch_size
(alias: kv.transaction.write_pipelining_max_batch_size)
integer128if non-zero, defines that maximum size batch that will be pipelined through Raft consensusBasic/Standard/Advanced/Self-Hosted
kvadmission.store.provisioned_bandwidth
byte size0 Bif set to a non-zero value, this is used as the provisioned bandwidth (in bytes/s), for each store. It can be overridden on a per-store basis using the --store flag. Note that setting the provisioned bandwidth to a positive value may enable disk bandwidth based admission control, since admission.disk_bandwidth_tokens.elastic.enabled defaults to trueAdvanced/Self-Hosted
kvadmission.store.snapshot_ingest_bandwidth_control.enabled
booleantrueif set to true, snapshot ingests will be subject to disk write control in ACAdvanced/Self-Hosted
log.channel_compatibility_mode.enabled
booleantruewhen true, logs will continue to log to the expected logging channels; when false, logs will be moved to new logging channels as part of a logging channel consolidation effortBasic/Standard/Advanced/Self-Hosted
obs.tablemetadata.automatic_updates.enabled
booleanfalseenables automatic updates of the table metadata cache system.table_metadataBasic/Standard/Advanced/Self-Hosted
obs.tablemetadata.data_valid_duration
duration20m0sthe duration for which the data in system.table_metadata is considered validBasic/Standard/Advanced/Self-Hosted
schedules.backup.gc_protection.enabled
booleantrueenable chaining of GC protection across backups run as part of a scheduleBasic/Standard/Advanced/Self-Hosted
security.client_cert.subject_required.enabled
booleanfalsemandates a requirement for subject role to be set for db userAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
security.ocsp.mode
enumerationoffuse OCSP to check whether TLS certificates are revoked. If the OCSP server is unreachable, in strict mode all certificates will be rejected and in lax mode all certificates will be accepted. [off = 0, lax = 1, strict = 2]Basic/Standard/Advanced/Self-Hosted
security.ocsp.timeout
duration3stimeout before considering the OCSP server unreachableBasic/Standard/Advanced/Self-Hosted
security.provisioning.ldap.enabled
booleanfalseenables automatic creation of SQL users upon successful LDAP loginBasic/Standard/Advanced/Self-Hosted
server.auth_log.sql_connections.enabled
booleanfalseif set, log SQL client connect and disconnect events to the SESSIONS log channel (note: may hinder performance on loaded nodes)Basic/Standard/Advanced/Self-Hosted
server.auth_log.sql_sessions.enabled
booleanfalseif set, log verbose SQL session authentication events to the SESSIONS log channel (note: may hinder performance on loaded nodes). Session start and end events are always logged regardless of this setting; disable the SESSIONS log channel to suppress them.Basic/Standard/Advanced/Self-Hosted
server.authentication_cache.enabled
booleantrueenables a cache used during authentication to avoid lookups to system tables when retrieving per-user authentication-related informationBasic/Standard/Advanced/Self-Hosted
server.child_metrics.enabled
booleanfalseenables the exporting of child metrics, additional prometheus time series with extra labelsBasic/Standard/Advanced/Self-Hosted
server.child_metrics.include_aggregate.enabled
booleantrueinclude the reporting of the aggregate time series when child metrics are enabled. This cluster setting has no effect if child metrics are disabled.Basic/Standard/Advanced/Self-Hosted
server.clock.forward_jump_check.enabled
(alias: server.clock.forward_jump_check_enabled)
booleanfalseif enabled, forward clock jumps > max_offset/2 will cause a panicBasic/Standard/Advanced/Self-Hosted
server.clock.persist_upper_bound_interval
duration0sthe interval between persisting the wall time upper bound of the clock. The clock does not generate a wall time greater than the persisted timestamp and will panic if it sees a wall time greater than this value. When cockroach starts, it waits for the wall time to catch-up till this persisted timestamp. This guarantees monotonic wall time across server restarts. Not setting this or setting a value of 0 disables this feature.Basic/Standard/Advanced/Self-Hosted
server.consistency_check.max_rate
byte size8.0 MiBthe rate limit (bytes/sec) to use for consistency checks; used in conjunction with server.consistency_check.interval to control the frequency of consistency checks. Note that setting this too high can negatively impact performance.Advanced/Self-Hosted
server.eventlog.enabled
booleantrueif set, logged notable events are also stored in the table system.eventlogBasic/Standard/Advanced/Self-Hosted
server.eventlog.ttl
duration2160h0m0sif nonzero, entries in system.eventlog older than this duration are periodically purgedBasic/Standard/Advanced/Self-Hosted
server.host_based_authentication.configuration
stringhost-based authentication configuration to use during connection authenticationBasic/Standard/Advanced/Self-Hosted
server.hot_ranges_request.node.timeout
duration5m0sthe duration allowed for a single node to return hot range data before the request is cancelled; if set to 0, there is no timeoutBasic/Standard/Advanced/Self-Hosted
server.hsts.enabled
booleanfalseif true, HSTS headers will be sent along with all HTTP requests. The headers will contain a max-age setting of one year. Browsers honoring the header will always use HTTPS to access the DB Console. Ensure that TLS is correctly configured prior to enabling.Basic/Standard/Advanced/Self-Hosted
server.http.base_path
string/path to redirect the user to upon succcessful loginBasic/Standard/Advanced/Self-Hosted
server.identity_map.configuration
stringsystem-identity to database-username mappingsBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.audience
stringsets accepted audience values for JWT logins over the SQL interfaceBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.claim
stringsets the JWT claim that is parsed to get the usernameBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.client.timeout
duration15ssets the client timeout for external calls made during JWT authentication (e.g. fetching JWKS, etc.)Basic/Standard/Advanced/Self-Hosted
server.jwt_authentication.enabled
booleanfalseenables or disables JWT login for the SQL interfaceBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.issuers.configuration
(alias: server.jwt_authentication.issuers)
stringsets accepted issuer values for JWT logins over the SQL interface which can be a single issuer URL string or a JSON string containing an array of issuer URLs or a JSON object containing map of issuer URLS to JWKS URIsBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.issuers.custom_ca
stringsets the PEM encoded custom root CA for verifying certificates while fetching JWKSBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.jwks
string{"keys":[]}sets the public key set for JWT logins over the SQL interface (JWKS format)Basic/Standard/Advanced/Self-Hosted
server.jwt_authentication.jwks_auto_fetch.enabled
booleanfalseenables or disables automatic fetching of JWKS from the issuer's well-known endpoint or JWKS URI set in JWTAuthIssuersConfig. If this is enabled, the server.jwt_authentication.jwks will be ignored.Basic/Standard/Advanced/Self-Hosted
server.ldap_authentication.client.tls_certificate
stringsets the client certificate PEM for establishing mTLS connection with LDAP serverBasic/Standard/Advanced/Self-Hosted
server.ldap_authentication.client.tls_key
stringsets the client key PEM for establishing mTLS connection with LDAP serverBasic/Standard/Advanced/Self-Hosted
server.ldap_authentication.domain.custom_ca
stringsets the PEM encoded custom root CA for verifying domain certificates when establishing connection with LDAP serverBasic/Standard/Advanced/Self-Hosted
server.log_gc.max_deletions_per_cycle
integer1000the maximum number of entries to delete on each purge of log-like system tablesBasic/Standard/Advanced/Self-Hosted
server.log_gc.period
duration1h0m0sthe period at which log-like system tables are checked for old entriesBasic/Standard/Advanced/Self-Hosted
server.max_connections_per_gateway
integer-1the maximum number of SQL connections per gateway allowed at a given time (note: this will only limit future connection attempts and will not affect already established connections). Negative values result in unlimited number of connections. Superusers are not affected by this limit.Basic/Standard/Advanced/Self-Hosted
server.max_open_transactions_per_gateway
integer-1the maximum number of open SQL transactions per gateway allowed at a given time. Negative values result in unlimited number of connections. Superusers are not affected by this limit.Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.autologin.enabled
(alias: server.oidc_authentication.autologin)
booleanfalseif true, logged-out visitors to the DB Console will be automatically redirected to the OIDC login endpointBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.button_text
stringLog in with your OIDC providertext to show on button on DB Console login page to login with your OIDC provider (only shown if OIDC is enabled)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.claim_json_key
stringsets JSON key of principal to extract from payload after OIDC authentication completes (usually email or sid)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.client.timeout
duration15ssets the client timeout for external calls made during OIDC authentication (e.g. authorization code flow, etc.)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.client_id
stringsets OIDC client idBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.client_secret
stringsets OIDC client secretBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.enabled
booleanfalseenables or disabled OIDC login for the DB ConsoleBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.principal_regex
string(.+)regular expression to apply to extracted principal (see claim_json_key setting) to translate to SQL user (golang regex format, must include 1 grouping to extract)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.provider.custom_ca
stringsets the PEM encoded custom root CA for verifying certificates while authenticating through the OIDC providerBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.provider_url
stringsets OIDC provider URL ({provider_url}/.well-known/openid-configuration must resolve)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.redirect_url
stringhttps://localhost:8080/oidc/v1/callbacksets OIDC redirect URL via a URL string or a JSON string containing a required `redirect_urls` key with an object that maps from region keys to URL strings (URLs should point to your load balancer and must route to the path /oidc/v1/callback)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.scopes
stringopenidsets OIDC scopes to include with authentication request (space delimited list of strings, required to start with `openid`)Basic/Standard/Advanced/Self-Hosted
server.rangelog.ttl
duration720h0m0sif nonzero, entries in system.rangelog older than this duration are periodically purgedAdvanced/Self-Hosted
server.redact_sensitive_settings.enabled
booleanfalseenables or disables the redaction of sensitive settings in the output of SHOW CLUSTER SETTINGS and SHOW ALL CLUSTER SETTINGS for users without the MODIFYCLUSTERSETTING privilegeBasic/Standard/Advanced/Self-Hosted
server.shutdown.connections.timeout
(alias: server.shutdown.connection_wait)
duration0sthe maximum amount of time a server waits for all SQL connections to be closed before proceeding with a drain. (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Basic/Standard/Advanced/Self-Hosted
server.shutdown.initial_wait
(alias: server.shutdown.drain_wait)
duration0sthe amount of time a server waits in an unready state before proceeding with a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting. --drain-wait is to specify the duration of the whole draining process, while server.shutdown.initial_wait is to set the wait time for health probes to notice that the node is not ready.)Basic/Standard/Advanced/Self-Hosted
server.shutdown.lease_transfer_iteration.timeout
(alias: server.shutdown.lease_transfer_wait)
duration5sthe timeout for a single iteration of the range lease transfer phase of draining (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Advanced/Self-Hosted
server.shutdown.transactions.timeout
(alias: server.shutdown.query_wait)
duration10sthe timeout for waiting for active transactions to finish during a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Basic/Standard/Advanced/Self-Hosted
server.sql_tcp_keep_alive.count
integer3maximum number of probes that will be sent out before a connection is dropped because it's unresponsive (Linux and Darwin only)Basic/Standard/Advanced/Self-Hosted
server.sql_tcp_keep_alive.interval
duration10stime between keep alive probes and idle time before probes are sent outBasic/Standard/Advanced/Self-Hosted
server.time_until_store_dead
duration5m0sthe time after which if there is no new gossiped information about a store, it is considered deadBasic/Standard/Advanced/Self-Hosted
server.user_login.cert_password_method.auto_scram_promotion.enabled
booleantruewhether to automatically promote cert-password authentication to use SCRAMBasic/Standard/Advanced/Self-Hosted
server.user_login.downgrade_scram_stored_passwords_to_bcrypt.enabled
booleantrueif server.user_login.password_encryption=crdb-bcrypt, this controls whether to automatically re-encode stored passwords using scram-sha-256 to crdb-bcryptBasic/Standard/Advanced/Self-Hosted
server.user_login.min_password_length
integer1the minimum length accepted for passwords set in cleartext via SQL. Note that a value lower than 1 is ignored: passwords cannot be empty in any case. This setting only applies when adding new users or altering an existing user's password; it will not affect existing logins.Basic/Standard/Advanced/Self-Hosted
server.user_login.password_encryption
enumerationscram-sha-256which hash method to use to encode cleartext passwords passed via ALTER/CREATE USER/ROLE WITH PASSWORD [crdb-bcrypt = 2, scram-sha-256 = 3]Basic/Standard/Advanced/Self-Hosted
server.user_login.password_hashes.default_cost.crdb_bcrypt
integer10the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method crdb-bcrypt (allowed range: 4-31)Basic/Standard/Advanced/Self-Hosted
server.user_login.password_hashes.default_cost.scram_sha_256
integer10610the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method scram-sha-256 (allowed range: 4096-240000000000)Basic/Standard/Advanced/Self-Hosted
server.user_login.rehash_scram_stored_passwords_on_cost_change.enabled
booleantrueif server.user_login.password_hashes.default_cost.scram_sha_256 differs from, the cost in a stored hash, this controls whether to automatically re-encode stored passwords using scram-sha-256 with the new default costBasic/Standard/Advanced/Self-Hosted
server.user_login.timeout
duration10stimeout after which client authentication times out if some system range is unavailable (0 = no timeout)Basic/Standard/Advanced/Self-Hosted
server.user_login.upgrade_bcrypt_stored_passwords_to_scram.enabled
booleantrueif server.user_login.password_encryption=scram-sha-256, this controls whether to automatically re-encode stored passwords using crdb-bcrypt to scram-sha-256Basic/Standard/Advanced/Self-Hosted
server.web_session.purge.ttl
duration1h0m0sif nonzero, entries in system.web_sessions older than this duration are periodically purgedBasic/Standard/Advanced/Self-Hosted
server.web_session.timeout
(alias: server.web_session_timeout)
duration168h0m0sthe duration that a newly created web session will be validBasic/Standard/Advanced/Self-Hosted
spanconfig.bounds.enabled
booleantruedictates whether span config bounds are consulted when serving span configs for secondary tenantsAdvanced/Self-Hosted
spanconfig.range_coalescing.system.enabled
(alias: spanconfig.storage_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs, for the ranges specific to the system tenantAdvanced/Self-Hosted
spanconfig.range_coalescing.application.enabled
(alias: spanconfig.tenant_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs across all secondary tenant keyspacesAdvanced/Self-Hosted
sql.auth.change_own_password.enabled
booleanfalsecontrols whether a user is allowed to change their own password, even if they have no other privilegesBasic/Standard/Advanced/Self-Hosted
sql.auth.grant_option_for_owner.enabled
booleantruedetermines whether the GRANT OPTION for privileges is implicitly given to the owner of an objectBasic/Standard/Advanced/Self-Hosted
sql.auth.grant_option_inheritance.enabled
booleantruedetermines whether the GRANT OPTION for privileges is inherited through role membershipBasic/Standard/Advanced/Self-Hosted
sql.auth.public_schema_create_privilege.enabled
booleantruedetermines whether to grant all users the CREATE privileges on the public schema when it is createdBasic/Standard/Advanced/Self-Hosted
sql.auth.skip_underlying_view_privilege_checks.enabled
booleantruedetermines whether to skip privilege checks on tables underlying views. When enabled, users with SELECT privileges on a view can query it regardless of their privileges on the underlying tables, and row-level security policies are evaluated as the invoking user rather than the view owner. This restores pre-v26.2 behavior.Basic/Standard/Advanced/Self-Hosted
sql.catalog.allow_leased_descriptors.enabled
booleanfalseif true, catalog views (crdb_internal, information_schema, pg_catalog) can use leased descriptors for improved performanceBasic/Standard/Advanced/Self-Hosted
sql.closed_session_cache.capacity
integer1000the maximum number of sessions in the cacheBasic/Standard/Advanced/Self-Hosted
sql.closed_session_cache.time_to_live
integer3600the maximum time to live, in secondsBasic/Standard/Advanced/Self-Hosted
sql.contention.event_store.capacity
byte size64 MiBthe in-memory storage capacity per-node of contention event storeBasic/Standard/Advanced/Self-Hosted
sql.contention.event_store.duration_threshold
duration0sminimum contention duration to cause the contention events to be collected into crdb_internal.transaction_contention_eventsBasic/Standard/Advanced/Self-Hosted
sql.contention.record_serialization_conflicts.enabled
booleantrueenables recording 40001 errors with conflicting txn meta as SERIALIZATION_CONFLICTcontention events into crdb_internal.transaction_contention_eventsBasic/Standard/Advanced/Self-Hosted
sql.contention.txn_id_cache.max_size
byte size64 MiBthe maximum byte size TxnID cache will use (set to 0 to disable)Basic/Standard/Advanced/Self-Hosted
sql.cross_db_fks.enabled
booleanfalseif true, creating foreign key references across databases is allowedBasic/Standard/Advanced/Self-Hosted
sql.cross_db_sequence_owners.enabled
booleanfalseif true, creating sequences owned by tables from other databases is allowedBasic/Standard/Advanced/Self-Hosted
sql.cross_db_sequence_references.enabled
booleanfalseif true, sequences referenced by tables from other databases are allowedBasic/Standard/Advanced/Self-Hosted
sql.cross_db_views.enabled
booleanfalseif true, creating views that refer to other databases is allowedBasic/Standard/Advanced/Self-Hosted
sql.defaults.cost_scans_with_default_col_size.enabled
booleanfalsesetting to true uses the same size for all columns to compute scan cost
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.datestyle
enumerationiso, mdydefault value for DateStyle session setting [iso, mdy = 0, iso, dmy = 1, iso, ymd = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.default_hash_sharded_index_bucket_count
integer16used as bucket count if bucket count is not specified in hash sharded index definition
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.default_int_size
integer8the size, in bytes, of an INT type
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.disallow_full_table_scans.enabled
booleanfalsesetting to true rejects queries that have planned a full table scan; set large_full_scan_rows > 0 to allow small full table scans estimated to read fewer than large_full_scan_rows
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.distsql
enumerationautodefault distributed SQL execution mode [off = 0, auto = 1, on = 2, always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_alter_column_type.enabled
booleanfalsedefault value for experimental_alter_column_type session setting; enables the use of ALTER COLUMN TYPE for general conversions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_distsql_planning
enumerationoffdefault experimental_distsql_planning mode; enables experimental opt-driven DistSQL planning [off = 0, on = 1]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_enable_unique_without_index_constraints.enabled
booleanfalsedefault value for experimental_enable_unique_without_index_constraints session setting;disables unique without index constraints by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_implicit_column_partitioning.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for the use of implicit column partitioning
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_temporary_tables.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for use of temporary tables by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.foreign_key_cascades_limit
integer10000default value for foreign_key_cascades_limit session setting; limits the number of cascading operations that run as part of a single query
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.idle_in_session_timeout
duration0sdefault value for the idle_in_session_timeout; default value for the idle_in_session_timeout session setting; controls the duration a session is permitted to idle before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.idle_in_transaction_session_timeout
duration0sdefault value for the idle_in_transaction_session_timeout; controls the duration a session is permitted to idle in a transaction before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.implicit_select_for_update.enabled
booleantruedefault value for enable_implicit_select_for_update session setting; enables FOR UPDATE locking during the row-fetch phase of mutation statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.insert_fast_path.enabled
booleantruedefault value for enable_insert_fast_path session setting; enables a specialized insert path
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.intervalstyle
enumerationpostgresdefault value for IntervalStyle session setting [postgres = 0, iso_8601 = 1, sql_standard = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.large_full_scan_rows
float0default value for large_full_scan_rows session variable which determines the table size at which full scans are considered large and disallowed when disallow_full_table_scans is set to true; set to 0 to reject all full table or full index scans when disallow_full_table_scans is true
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.locality_optimized_partitioned_index_scan.enabled
booleantruedefault value for locality_optimized_partitioned_index_scan session setting; enables searching for rows in the current region before searching remote regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.lock_timeout
duration0sdefault value for the lock_timeout; default value for the lock_timeout session setting; controls the duration a query is permitted to wait while attempting to acquire a lock on a key or while blocking on an existing lock in order to perform a non-locking read on a key; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.on_update_rehome_row.enabled
booleantruedefault value for on_update_rehome_row; enables ON UPDATE rehome_row() expressions to trigger on updates
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.optimizer_use_histograms.enabled
booleantruedefault value for optimizer_use_histograms session setting; enables usage of histograms in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.optimizer_use_multicol_stats.enabled
booleantruedefault value for optimizer_use_multicol_stats session setting; enables usage of multi-column stats in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.override_alter_primary_region_in_super_region.enabled
booleanfalsedefault value for override_alter_primary_region_in_super_region; allows for altering the primary region even if the primary region is a member of a super region
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.override_multi_region_zone_config.enabled
booleanfalsedefault value for override_multi_region_zone_config; allows for overriding the zone configs of a multi-region table or database
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.prefer_lookup_joins_for_fks.enabled
booleanfalsedefault value for prefer_lookup_joins_for_fks session setting; causes foreign key operations to use lookup joins when possible
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.primary_region
stringif not empty, all databases created without a PRIMARY REGION will implicitly have the given PRIMARY REGION
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.reorder_joins_limit
integer8default number of joins to reorder
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.require_explicit_primary_keys.enabled
booleanfalsedefault value for requiring explicit primary keys in CREATE TABLE statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.results_buffer.size
byte size512 KiBdefault size of the buffer that accumulates results for a statement or a batch of statements before they are sent to the client. This can be overridden on an individual connection with the 'results_buffer_size' parameter. Note that auto-retries generally only happen while no results have been delivered to the client, so reducing this size can increase the number of retriable errors a client receives. On the other hand, increasing the buffer size can increase the delay until the client receives the first result row. Updating the setting only affects new connections. Setting to 0 disables any buffering.
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.serial_normalization
enumerationrowiddefault handling of SERIAL in table definitions [rowid = 0, virtual_sequence = 1, sql_sequence = 2, sql_sequence_cached = 3, unordered_rowid = 4, sql_sequence_cached_node = 5]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.statement_timeout
duration0sdefault value for the statement_timeout; default value for the statement_timeout session setting; controls the duration a query is permitted to run before it is canceled; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.stub_catalog_tables.enabled
booleantruedefault value for stub_catalog_tables session setting
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.super_regions.enabled
booleanfalsedefault value for enable_super_regions; allows for the usage of super regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.transaction_rows_read_err
integer0the limit for the number of rows read by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.transaction_rows_read_log
integer0the threshold for the number of rows read by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.transaction_rows_written_err
integer0the limit for the number of rows written by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.transaction_rows_written_log
integer0the threshold for the number of rows written by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.use_declarative_schema_changer
enumerationondefault value for use_declarative_schema_changer session setting;disables new schema changer by default [off = 0, on = 1, unsafe = 2, unsafe_always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.vectorize
enumerationondefault vectorize mode [on = 0, on = 1, on = 2, experimental_always = 3, off = 4]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.zigzag_join.enabled
booleanfalsedefault value for enable_zigzag_join session setting; disallows use of zig-zag join by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.distsql.temp_storage.workmem
byte size64 MiBmaximum amount of memory in bytes a processor can use before falling back to temp storageBasic/Standard/Advanced/Self-Hosted
sql.guardrails.max_row_size_err
byte size512 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an error is returned; use 0 to disableBasic/Standard/Advanced/Self-Hosted
sql.guardrails.max_row_size_log
byte size64 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an event is logged to SQL_PERF (or SQL_INTERNAL_PERF if the mutating statement was internal); use 0 to disableBasic/Standard/Advanced/Self-Hosted
sql.hash_sharded_range_pre_split.max
integer16max pre-split ranges to have when adding hash sharded index to an existing tableBasic/Standard/Advanced/Self-Hosted
sql.index_recommendation.drop_unused_duration
duration168h0m0sthe index unused duration at which we begin to recommend dropping the indexBasic/Standard/Advanced/Self-Hosted
sql.insights.anomaly_detection.enabled
booleantrueenable per-fingerprint latency recording and anomaly detectionBasic/Standard/Advanced/Self-Hosted
sql.insights.anomaly_detection.latency_threshold
duration50msstatements must surpass this threshold to trigger anomaly detection and identificationBasic/Standard/Advanced/Self-Hosted
sql.insights.anomaly_detection.memory_limit
byte size1.0 MiBthe maximum amount of memory allowed for tracking statement latenciesBasic/Standard/Advanced/Self-Hosted
sql.insights.execution_insights_capacity
integer1000the size of the per-node store of execution insightsBasic/Standard/Advanced/Self-Hosted
sql.insights.high_retry_count.threshold
integer10the number of retries a slow statement must have undergone for its high retry count to be highlighted as a potential problemBasic/Standard/Advanced/Self-Hosted
sql.insights.latency_threshold
duration100msamount of time after which an executing statement is considered slow. Use 0 to disable.Basic/Standard/Advanced/Self-Hosted
sql.log.redact_names.enabled
booleanfalseif set, schema object identifers are redacted in SQL statements that appear in event logsBasic/Standard/Advanced/Self-Hosted
sql.log.scan_row_count_misestimate.enabled
booleanfalsewhen set to true, log a warning when a scan's actual row count differs significantly from the optimizer's estimateBasic/Standard/Advanced/Self-Hosted
sql.log.slow_query.experimental_full_table_scans.enabled
booleanfalsewhen set to true, statements that perform a full table/index scan will be logged to the slow query log even if they do not meet the latency threshold. Must have the slow query log enabled for this setting to have any effect.Basic/Standard/Advanced/Self-Hosted
sql.log.slow_query.internal_queries.enabled
booleanfalsewhen set to true, internal queries which exceed the slow query log threshold are logged to a separate log. Must have the slow query log enabled for this setting to have any effect.Basic/Standard/Advanced/Self-Hosted
sql.log.slow_query.latency_threshold
duration0swhen set to non-zero, log statements whose service latency exceeds the threshold to a secondary logger on each nodeBasic/Standard/Advanced/Self-Hosted
sql.log.user_audit
stringuser/role-based audit logging configuration. An enterprise license is required for this cluster setting to take effect.Basic/Standard/Advanced/Self-Hosted
sql.log.user_audit.reduced_config.enabled
booleanfalseenables logic to compute a reduced audit configuration, computing the audit configuration only once at session start instead of at each SQL event. The tradeoff with the increase in performance (~5%), is that changes to the audit configuration (user role memberships/cluster setting) are not reflected within session. Users will need to start a new session to see these changes in their auditing behaviour.Basic/Standard/Advanced/Self-Hosted
sql.metrics.application_name.enabled
booleanfalsewhen enabled, SQL metrics would export application name as and additional label as part of child metrics. The number of unique label combinations is limited to 5000 by default.Basic/Standard/Advanced/Self-Hosted
sql.metrics.database_name.enabled
booleanfalsewhen enabled, SQL metrics would export database name as and additional label as part of child metrics. The number of unique label combinations is limited to 5000 by default.Basic/Standard/Advanced/Self-Hosted
sql.metrics.index_usage_stats.enabled
booleantruecollect per index usage statisticsBasic/Standard/Advanced/Self-Hosted
sql.metrics.max_mem_reported_stmt_fingerprints
integer100000the maximum number of reported statement fingerprints stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.max_mem_reported_txn_fingerprints
integer100000the maximum number of reported transaction fingerprints stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.max_mem_stmt_fingerprints
integer7500the maximum number of statement fingerprints stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.max_mem_txn_fingerprints
integer7500the maximum number of transaction fingerprints stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.dump_to_logs.enabled
(alias: sql.metrics.statement_details.dump_to_logs)
booleanfalsedump collected statement statistics to node logs when periodically clearedBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.enabled
booleantruecollect per-statement query statisticsBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.gateway_node.enabled
booleanfalsesave the gateway node for each statement fingerprint. If false, the value will be stored as 0.Basic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.index_recommendation_collection.enabled
booleantruegenerate an index recommendation for each fingerprint IDBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.max_mem_reported_idx_recommendations
integer5000the maximum number of reported index recommendation info stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.threshold
duration0sminimum execution time to cause statement statistics to be collected. If configured, no transaction stats are collected.Basic/Standard/Advanced/Self-Hosted
sql.metrics.transaction_details.enabled
booleantruecollect per-application transaction statisticsBasic/Standard/Advanced/Self-Hosted
sql.multiple_modifications_of_table.enabled
booleanfalseif true, allow statements containing multiple INSERT ON CONFLICT, UPSERT, UPDATE, or DELETE subqueries modifying the same table, at the risk of data corruption if the same row is modified multiple times by a single statement (multiple INSERT subqueries without ON CONFLICT cannot cause corruption and are always allowed)Basic/Standard/Advanced/Self-Hosted
sql.multiregion.drop_primary_region.enabled
booleantrueallows dropping the PRIMARY REGION of a database if it is the last regionBasic/Standard/Advanced/Self-Hosted
sql.notices.enabled
booleantrueenable notices in the server/client protocol being sentBasic/Standard/Advanced/Self-Hosted
sql.optimizer.uniqueness_checks_for_gen_random_uuid.enabled
booleanfalseif enabled, uniqueness checks may be planned for mutations of UUID columns updated with gen_random_uuid(); otherwise, uniqueness is assumed due to near-zero collision probabilityBasic/Standard/Advanced/Self-Hosted
sql.schema.approx_max_object_count
integer20000approximate maximum number of schema objects allowed in the cluster; the check uses cached statistics, so the actual count may slightly exceed this limit; set to 0 to disableBasic/Standard/Advanced/Self-Hosted
sql.schema.auto_unlock.enabled
booleantruecontrols whether DDL operations will attempt to automatically unlock and re-lock schema_locked tables. When this setting is false, DDL on schema_locked tables is blocked unless the user manually unlocks the table first. The schema_locked storage parameter improves changefeed performance by locking the table's schema from the perspective of the changefeed.Basic/Standard/Advanced/Self-Hosted
sql.schema.telemetry.recurrence
string@weeklycron-tab recurrence for SQL schema telemetry jobAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
sql.spatial.experimental_box2d_comparison_operators.enabled
booleanfalseenables the use of certain experimental box2d comparison operatorsBasic/Standard/Advanced/Self-Hosted
sql.sqlcommenter.enabled
booleanfalseenables support for sqlcommenter. Key value parsed from sqlcommenter comments will be included in sql insights and sql logs. See https://google.github.io/sqlcommenter/ for more details.Basic/Standard/Advanced/Self-Hosted
sql.stats.activity.persisted_rows.max
integer200000maximum number of rows of statement and transaction activity that will be persisted in the system tablesBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_collection.enabled
booleantrueautomatic statistics collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_collection.fraction_stale_rows
float0.2target fraction of stale rows per table that will trigger a statistics refreshBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_collection.min_stale_rows
integer500target minimum number of stale rows per table that will trigger a statistics refreshBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_full_collection.enabled
booleantrueautomatic full statistics collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_partial_collection.enabled
booleantrueautomatic partial statistics collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_partial_collection.fraction_stale_rows
float0.05target fraction of stale rows per table that will trigger a partial statistics refreshBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_partial_collection.min_stale_rows
integer100target minimum number of stale rows per table that will trigger a partial statistics refreshBasic/Standard/Advanced/Self-Hosted
sql.stats.cleanup.recurrence
string@hourlycron-tab recurrence for SQL Stats cleanup jobBasic/Standard/Advanced/Self-Hosted
sql.stats.detailed_latency_metrics.enabled
booleanfalselabel latency metrics with the statement fingerprint. Workloads with tens of thousands of distinct query fingerprints should leave this setting false. (experimental, affects performance for workloads with high fingerprint cardinality)Basic/Standard/Advanced/Self-Hosted
sql.stats.error_on_concurrent_create_stats.enabled
booleanfalseset to true to error on concurrent CREATE STATISTICS jobs, instead of skipping themBasic/Standard/Advanced/Self-Hosted
sql.stats.flush.enabled
booleantrueif set, SQL execution statistics are periodically flushed to diskBasic/Standard/Advanced/Self-Hosted
sql.stats.flush.interval
duration10m0sthe interval at which SQL execution statistics are flushed to disk, this value must be less than or equal to 1 hourBasic/Standard/Advanced/Self-Hosted
sql.stats.forecasts.enabled
booleantruewhen true, enables generation of statistics forecasts by default for all tablesBasic/Standard/Advanced/Self-Hosted
sql.stats.forecasts.max_decrease
float0.3333333333333333the most a prediction is allowed to decrease, expressed as the minimum ratio of the prediction to the lowest prior observationBasic/Standard/Advanced/Self-Hosted
sql.stats.forecasts.min_goodness_of_fit
float0.95the minimum R² (goodness of fit) measurement required from all predictive models to use a forecastBasic/Standard/Advanced/Self-Hosted
sql.stats.forecasts.min_observations
integer3the mimimum number of observed statistics required to produce a statistics forecastBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_buckets.count
integer200maximum number of histogram buckets to build during table statistics collectionBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_buckets.include_most_common_values.enabled
booleantruewhether to include most common values as histogram bucketsBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_buckets.max_fraction_most_common_values
float0.1maximum fraction of histogram buckets to use for most common valuesBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_collection.enabled
booleantruehistogram collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_samples.count
integer0number of rows sampled for histogram construction during table statistics collection. Not setting this or setting a value of 0 means that a reasonable sample size will be automatically picked based on the table size.Basic/Standard/Advanced/Self-Hosted
sql.stats.multi_column_collection.enabled
booleantruemulti-column statistics collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.non_default_columns.min_retention_period
duration24h0m0sminimum retention period for table statistics collected on non-default columnsBasic/Standard/Advanced/Self-Hosted
sql.stats.non_indexed_json_histograms.enabled
booleanfalseset to true to collect table statistics histograms on non-indexed JSON columnsBasic/Standard/Advanced/Self-Hosted
sql.stats.persisted_rows.max
integer1000000maximum number of rows of statement and transaction statistics that will be persisted in the system tables before compaction beginsBasic/Standard/Advanced/Self-Hosted
sql.stats.post_events.enabled
booleanfalseif set, an event is logged for every successful CREATE STATISTICS jobBasic/Standard/Advanced/Self-Hosted
sql.stats.response.max
integer20000the maximum number of statements and transaction stats returned in a CombinedStatements requestBasic/Standard/Advanced/Self-Hosted
sql.stats.response.show_internal.enabled
booleanfalsecontrols if statistics for internal executions should be returned by the CombinedStatements and if internal sessions should be returned by the ListSessions endpoints. These endpoints are used to display statistics on the SQL Activity pagesBasic/Standard/Advanced/Self-Hosted
sql.stats.system_tables.enabled
booleantruewhen true, enables use of statistics on system tables by the query optimizerBasic/Standard/Advanced/Self-Hosted
sql.stats.system_tables_autostats.enabled
booleantruewhen true, enables automatic collection of statistics on system tablesBasic/Standard/Advanced/Self-Hosted
sql.stats.table_statistics_cache.capacity
integer256the maximum number of table statistics entries stored in the LRU cache. Each cache entry corresponds to a single table.Basic/Standard/Advanced/Self-Hosted
sql.stats.virtual_computed_columns.enabled
booleantrueset to true to collect table statistics on virtual computed columnsBasic/Standard/Advanced/Self-Hosted
sql.telemetry.query_sampling.enabled
booleanfalsewhen set to true, executed queries will emit an event on the telemetry logging channelBasic/Standard/Advanced/Self-Hosted
sql.telemetry.query_sampling.internal.enabled
booleanfalsewhen set to true, internal queries will be sampled in telemetry loggingBasic/Standard/Advanced/Self-Hosted
sql.telemetry.query_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample executions for telemetry, note that it is recommended that this value shares a log-line limit of 10 logs per second on the telemetry pipeline with all other telemetry events. If sampling mode is set to 'transaction', this value is ignored.Basic/Standard/Advanced/Self-Hosted
sql.telemetry.query_sampling.mode
enumerationstatementthe execution level used for telemetry sampling. If set to 'statement', events are sampled at the statement execution level. If set to 'transaction', events are sampled at the transaction execution level, i.e. all statements for a transaction will be logged and are counted together as one sampled event (events are still emitted one per statement). [statement = 0, transaction = 1]Basic/Standard/Advanced/Self-Hosted
sql.telemetry.transaction_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample transactions for telemetry. If sampling mode is set to 'statement', this setting is ignored. In practice, this means that we only sample a transaction if 1/max_event_frequency seconds have elapsed since the last transaction was sampled.Basic/Standard/Advanced/Self-Hosted
sql.telemetry.transaction_sampling.statement_events_per_transaction.max
integer50the maximum number of statement events to log for every sampled transaction. Note that statements that are logged by force do not adhere to this limit.Basic/Standard/Advanced/Self-Hosted
sql.temp_object_cleaner.cleanup_interval
duration30m0show often to clean up orphaned temporary objectsBasic/Standard/Advanced/Self-Hosted
sql.temp_object_cleaner.wait_interval
duration30m0show long after creation a temporary object will be cleaned upBasic/Standard/Advanced/Self-Hosted
sql.log.all_statements.enabled
(alias: sql.trace.log_statement_execute)
booleanfalseset to true to enable logging of all executed statementsBasic/Standard/Advanced/Self-Hosted
sql.trace.stmt.enable_threshold
duration0senables tracing on all statements; statements executing for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting applies to individual statements within a transaction and is therefore finer-grained than sql.trace.txn.enable_thresholdBasic/Standard/Advanced/Self-Hosted
sql.trace.txn.enable_threshold
duration0senables transaction traces for transactions exceeding this duration, used with `sql.trace.txn.sample_rate`Basic/Standard/Advanced/Self-Hosted
sql.trace.txn.include_internal.enabled
booleantrueenables tracing internal transactions as well as external workload using sample rate and threshold settingsBasic/Standard/Advanced/Self-Hosted
sql.trace.txn.jaeger_json_output.enabled
booleanfalseenables Jaeger JSON output for transaction traces in logsBasic/Standard/Advanced/Self-Hosted
sql.trace.txn.sample_rate
float1enables probabilistic transaction tracing. It should be used in conjunction with `sql.trace.txn.enable_threshold`. A percentage of transactions between 0 and 1.0 will have tracing enabled, and only those which exceed the configured threshold will be logged.Basic/Standard/Advanced/Self-Hosted
sql.ttl.changefeed_replication.disabled
booleanfalseif true, deletes issued by TTL will not be replicated via changefeeds (this setting will be ignored by changefeeds that have the ignore_disable_changefeed_replication option set; such changefeeds will continue to replicate all TTL deletes)Basic/Standard/Advanced/Self-Hosted
sql.ttl.default_delete_batch_size
integer100default amount of rows to delete in a single query during a TTL jobBasic/Standard/Advanced/Self-Hosted
sql.ttl.default_delete_rate_limit
integer100default delete rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Basic/Standard/Advanced/Self-Hosted
sql.ttl.default_select_batch_size
integer500default amount of rows to select in a single query during a TTL jobBasic/Standard/Advanced/Self-Hosted
sql.ttl.default_select_rate_limit
integer0default select rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Basic/Standard/Advanced/Self-Hosted
sql.ttl.job.enabled
booleantruewhether the TTL job is enabledBasic/Standard/Advanced/Self-Hosted
sql.txn.read_committed_isolation.enabled
booleantrueset to true to allow transactions to use the READ COMMITTED isolation level if specified by BEGIN/SET commandsBasic/Standard/Advanced/Self-Hosted
sql.txn.repeatable_read_isolation.enabled
(alias: sql.txn.snapshot_isolation.enabled)
booleanfalseset to true to allow transactions to use the REPEATABLE READ isolation level if specified by BEGIN/SET commandsBasic/Standard/Advanced/Self-Hosted
sql.txn_fingerprint_id_cache.capacity
integer100the maximum number of txn fingerprint IDs storedBasic/Standard/Advanced/Self-Hosted
sql.vecindex.stalled_op.timeout
duration100msamount of time before other vector index workers will assist with a stalled background fixupBasic/Standard/Advanced/Self-Hosted
storage.delete_compaction_excise.enabled
booleantrueset to false to direct Pebble to not partially excise sstables in delete-only compactionsAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.ingest_split.enabled
booleantrueset to false to disable ingest-time splitting that lowers write-amplificationAdvanced/Self-Hosted
storage.ingestion.value_blocks.enabled
booleantrueset to true to enable writing of value blocks in ingestion sstablesBasic/Standard/Advanced/Self-Hosted
storage.max_sync_duration
duration20smaximum duration for disk operations; any operations that take longer than this setting trigger a warning log entry or process crashAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.max_sync_duration.fatal.enabled
booleantrueif true, fatal the process when a disk operation exceeds storage.max_sync_durationBasic/Standard/Advanced/Self-Hosted
storage.sstable.compression_algorithm
enumerationfastestdetermines the compression algorithm to use for Pebble stores [snappy = 1, zstd = 2, none = 3, minlz = 4, fastest = 5, balanced = 6, good = 7, fast = 8]Advanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.sstable.compression_algorithm_backup_storage
enumerationfastestdetermines the compression algorithm to use when compressing sstable data blocks for backup row data storage (fast,balanced,good are experimental); [snappy = 1, zstd = 2, none = 3, minlz = 4, fastest = 5, fast = 6, balanced = 7, good = 8]Advanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.sstable.compression_algorithm_backup_transport
enumerationfastestdetermines the compression algorithm to use when compressing sstable data blocks for backup transport (fast,balanced,good are experimental); [snappy = 1, zstd = 2, none = 3, minlz = 4, fastest = 5, fast = 6, balanced = 7, good = 8]Advanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.unhealthy_write_duration
duration20sduration for disk write operations, beyond which the disk will be reported as unhealthy for higher layer actionsAdvanced/Self-Hosted
storage.wal_failover.unhealthy_op_threshold
duration100msthe latency of a WAL write considered unhealthy and triggers a failover to a secondary WAL locationAdvanced/Self-Hosted
timeseries.storage.enabled
booleantrueif set, periodic timeseries data is stored within the cluster; disabling is not recommended unless you are storing the data elsewhereAdvanced/Self-Hosted
timeseries.storage.resolution_10s.ttl
duration240h0m0sthe maximum age of time series data stored at the 10 second resolution. Data older than this is subject to rollup and deletion.Advanced/Self-hosted (read-write); Basic/Standard (read-only)
timeseries.storage.resolution_30m.ttl
duration2160h0m0sthe maximum age of time series data stored at the 30 minute resolution. Data older than this is subject to deletion.Advanced/Self-hosted (read-write); Basic/Standard (read-only)
trace.debug_http_endpoint.enabled
(alias: trace.debug.enable)
booleanfalseif set, traces for recent requests can be seen at https://<ui>/debug/requestsBasic/Standard/Advanced/Self-Hosted
trace.opentelemetry.collector
stringaddress of an OpenTelemetry trace collector to receive traces using the otel gRPC protocol, as <host>:<port>. If no port is specified, 4317 will be used.Basic/Standard/Advanced/Self-Hosted
trace.snapshot.rate
duration0sif non-zero, interval at which background trace snapshots are capturedBasic/Standard/Advanced/Self-Hosted
trace.span_registry.enabled
booleanfalseif set, ongoing traces can be seen at https://<ui>/#/debug/tracezBasic/Standard/Advanced/Self-Hosted
trace.zipkin.collector
stringthe address of a Zipkin instance to receive traces, as <host>:<port>. If no port is specified, 9411 will be used.Basic/Standard/Advanced/Self-Hosted
ui.database_locality_metadata.enabled
booleantrueif enabled shows extended locality data about databases and tables in DB Console which can be expensive to computeBasic/Standard/Advanced/Self-Hosted
ui.default_timezone
stringthe default timezone used to format timestamps in the uiBasic/Standard/Advanced/Self-Hosted
ui.display_timezone
enumerationetc/utcthe timezone used to format timestamps in the ui. This setting is deprecatedand will be removed in a future version. Use the 'ui.default_timezone' setting instead. 'ui.default_timezone' takes precedence over this setting. [etc/utc = 0, america/new_york = 1]Basic/Standard/Advanced/Self-Hosted
version
version25.4set the active cluster version in the format '<major>.<minor>'Basic/Standard/Advanced/Self-Hosted
diff --git a/src/current/_includes/cockroach-generated/release-25.4/sql/aggregates.md b/src/current/_includes/cockroach-generated/release-25.4/sql/aggregates.md new file mode 100644 index 00000000000..1683084408b --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.4/sql/aggregates.md @@ -0,0 +1,589 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_agg(arg1: bool) → bool[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bool[]) → bool[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes) → bytes[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes[]) → bytes[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date) → date[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date[]) → date[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal) → decimal[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal[]) → decimal[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float) → float[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float[]) → float[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet) → inet[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet[]) → inet[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int) → int[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int[]) → int[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval) → interval[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval[]) → interval[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string) → string[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string[]) → string[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time) → time[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time[]) → time[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp) → timestamp[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp[]) → timestamp[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz) → timestamptz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz[]) → timestamptz[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid) → uuid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid[]) → uuid[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum) → anyenum[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum[]) → anyenum[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d) → box2d[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d[]) → box2d[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography) → geography[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography[]) → geography[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry) → geometry[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry[]) → geometry[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb) → jsonb[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb[]) → jsonb[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: ltree) → ltree[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: ltree[]) → ltree[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid) → oid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid[]) → oid[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn) → pg_lsn[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn[]) → pg_lsn[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor) → refcursor[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor[]) → refcursor[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz) → timetz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz[]) → timetz[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple) → tuple[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple[]) → tuple[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit) → varbit[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit[]) → varbit[][]

Aggregates the selected values into an array.

+		Immutable
array_cat_agg(arg1: bool[]) → bool[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: bytes[]) → bytes[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: date[]) → date[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: decimal[]) → decimal[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: float[]) → float[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: inet[]) → inet[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: int[]) → int[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: interval[]) → interval[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: string[]) → string[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: time[]) → time[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamp[]) → timestamp[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamptz[]) → timestamptz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: uuid[]) → uuid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: anyenum[]) → anyenum[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: box2d[]) → box2d[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geography[]) → geography[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geometry[]) → geometry[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: jsonb[]) → jsonb[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: ltree[]) → ltree[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: oid[]) → oid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: pg_lsn[]) → pg_lsn[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: refcursor[]) → refcursor[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timetz[]) → timetz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: tuple[]) → tuple[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: varbit[]) → varbit[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
avg(arg1: decimal) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: float) → float

Calculates the average of the selected values.

+		Immutable
avg(arg1: int) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: interval) → interval

Calculates the average of the selected values.

+		Immutable
bit_and(arg1: int) → int

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_and(arg1: varbit) → varbit

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: int) → int

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: varbit) → varbit

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bool_and(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
bool_or(arg1: bool) → bool

Calculates the boolean value of ORing all selected values.

+		Immutable
concat_agg(arg1: bytes) → bytes

Concatenates all selected values.

+		Immutable
concat_agg(arg1: string) → string

Concatenates all selected values.

+		Immutable
corr(arg1: decimal, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
count(arg1: anyelement) → int

Calculates the number of selected elements.

+		Immutable
count_rows() → int

Calculates the number of rows.

+		Immutable
covar_pop(arg1: decimal, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
every(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
json_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
json_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
jsonb_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
jsonb_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
max(arg1: bool) → bool

Identifies the maximum selected value.

+		Immutable
max(arg1: bytes) → bytes

Identifies the maximum selected value.

+		Immutable
max(arg1: date) → date

Identifies the maximum selected value.

+		Immutable
max(arg1: decimal) → decimal

Identifies the maximum selected value.

+		Immutable
max(arg1: float) → float

Identifies the maximum selected value.

+		Immutable
max(arg1: inet) → inet

Identifies the maximum selected value.

+		Immutable
max(arg1: int) → int

Identifies the maximum selected value.

+		Immutable
max(arg1: interval) → interval

Identifies the maximum selected value.

+		Immutable
max(arg1: string) → string

Identifies the maximum selected value.

+		Immutable
max(arg1: time) → time

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamp) → timestamp

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamptz) → timestamptz

Identifies the maximum selected value.

+		Immutable
max(arg1: uuid) → uuid

Identifies the maximum selected value.

+		Immutable
max(arg1: anyenum) → anyenum

Identifies the maximum selected value.

+		Immutable
max(arg1: box2d) → box2d

Identifies the maximum selected value.

+		Immutable
max(arg1: collatedstring{*}) → collatedstring{*}

Identifies the maximum selected value.

+		Immutable
max(arg1: geography) → geography

Identifies the maximum selected value.

+		Immutable
max(arg1: geometry) → geometry

Identifies the maximum selected value.

+		Immutable
max(arg1: jsonb) → jsonb

Identifies the maximum selected value.

+		Immutable
max(arg1: ltree) → ltree

Identifies the maximum selected value.

+		Immutable
max(arg1: oid) → oid

Identifies the maximum selected value.

+		Immutable
max(arg1: pg_lsn) → pg_lsn

Identifies the maximum selected value.

+		Immutable
max(arg1: timetz) → timetz

Identifies the maximum selected value.

+		Immutable
max(arg1: varbit) → varbit

Identifies the maximum selected value.

+		Immutable
min(arg1: bool) → bool

Identifies the minimum selected value.

+		Immutable
min(arg1: bytes) → bytes

Identifies the minimum selected value.

+		Immutable
min(arg1: date) → date

Identifies the minimum selected value.

+		Immutable
min(arg1: decimal) → decimal

Identifies the minimum selected value.

+		Immutable
min(arg1: float) → float

Identifies the minimum selected value.

+		Immutable
min(arg1: inet) → inet

Identifies the minimum selected value.

+		Immutable
min(arg1: int) → int

Identifies the minimum selected value.

+		Immutable
min(arg1: interval) → interval

Identifies the minimum selected value.

+		Immutable
min(arg1: string) → string

Identifies the minimum selected value.

+		Immutable
min(arg1: time) → time

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamp) → timestamp

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamptz) → timestamptz

Identifies the minimum selected value.

+		Immutable
min(arg1: uuid) → uuid

Identifies the minimum selected value.

+		Immutable
min(arg1: anyenum) → anyenum

Identifies the minimum selected value.

+		Immutable
min(arg1: box2d) → box2d

Identifies the minimum selected value.

+		Immutable
min(arg1: collatedstring{*}) → collatedstring{*}

Identifies the minimum selected value.

+		Immutable
min(arg1: geography) → geography

Identifies the minimum selected value.

+		Immutable
min(arg1: geometry) → geometry

Identifies the minimum selected value.

+		Immutable
min(arg1: jsonb) → jsonb

Identifies the minimum selected value.

+		Immutable
min(arg1: ltree) → ltree

Identifies the minimum selected value.

+		Immutable
min(arg1: oid) → oid

Identifies the minimum selected value.

+		Immutable
min(arg1: pg_lsn) → pg_lsn

Identifies the minimum selected value.

+		Immutable
min(arg1: timetz) → timetz

Identifies the minimum selected value.

+		Immutable
min(arg1: varbit) → varbit

Identifies the minimum selected value.

+		Immutable
percentile_cont(arg1: float) → float

Continuous percentile: returns a float corresponding to the specified fraction in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float) → interval

Continuous percentile: returns an interval corresponding to the specified fraction in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_cont(arg1: float[]) → float[]

Continuous percentile: returns floats corresponding to the specified fractions in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float[]) → interval[]

Continuous percentile: returns intervals corresponding to the specified fractions in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_disc(arg1: float) → anyelement

Discrete percentile: returns the first input value whose position in the ordering equals or exceeds the specified fraction.

+		Immutable
percentile_disc(arg1: float[]) → anyelement

Discrete percentile: returns input values whose position in the ordering equals or exceeds the specified fractions.

+		Immutable
regr_avgx(arg1: decimal, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_count(arg1: decimal, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_intercept(arg1: decimal, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_r2(arg1: decimal, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_slope(arg1: decimal, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_sxx(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
sqrdiff(arg1: decimal) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: float) → float

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: int) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
st_collect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_extent(arg1: geometry) → box2d

Forms a Box2D that encapsulates all provided geometries.

+		Immutable
st_makeline(arg1: geometry) → geometry

Forms a LineString from Point, MultiPoint or LineStrings. Other shapes will be ignored.

+		Immutable
st_memcollect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_memunion(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
st_union(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
stddev(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: decimal) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: float) → float

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: int) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
string_agg(arg1: bytes, arg2: bytes) → bytes

Concatenates all selected values using the provided delimiter.

+		Immutable
string_agg(arg1: string, arg2: string) → string

Concatenates all selected values using the provided delimiter.

+		Immutable
sum(arg1: decimal) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: float) → float

Calculates the sum of the selected values.

+		Immutable
sum(arg1: int) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: interval) → interval

Calculates the sum of the selected values.

+		Immutable
sum_int(arg1: int) → int

Calculates the sum of the selected values.

+		Immutable
var_pop(arg1: decimal) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: float) → float

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: int) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_samp(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
variance(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
xor_agg(arg1: bytes) → bytes

Calculates the bitwise XOR of the selected values.

+		Immutable
xor_agg(arg1: int) → int

Calculates the bitwise XOR of the selected values.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-25.4/sql/functions.md b/src/current/_includes/cockroach-generated/release-25.4/sql/functions.md new file mode 100644 index 00000000000..8be2853fd67 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.4/sql/functions.md @@ -0,0 +1,3669 @@ +### Array functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_append(array: bool[], elem: bool) → bool[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: bytes[], elem: bytes) → bytes[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: date[], elem: date) → date[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: decimal[], elem: decimal) → decimal[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: float[], elem: float) → float[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: inet[], elem: inet) → inet[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: int[], elem: int) → int[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: interval[], elem: interval) → interval[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: string[], elem: string) → string[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: time[], elem: time) → time[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamp[], elem: timestamp) → timestamp[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamptz[], elem: timestamptz) → timestamptz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: uuid[], elem: uuid) → uuid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: anyenum[], elem: anyenum) → anyenum[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: box2d[], elem: box2d) → box2d[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geography[], elem: geography) → geography[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geometry[], elem: geometry) → geometry[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: jsonb[], elem: jsonb) → jsonb[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: ltree[], elem: ltree) → ltree[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: oid[], elem: oid) → oid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: refcursor[], elem: refcursor) → refcursor[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timetz[], elem: timetz) → timetz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: tuple[], elem: tuple) → tuple[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: varbit[], elem: varbit) → varbit[]

Appends elem to array, returning the result.

+		Immutable
array_cat(left: bool[], right: bool[]) → bool[]

Appends two arrays.

+		Immutable
array_cat(left: bytes[], right: bytes[]) → bytes[]

Appends two arrays.

+		Immutable
array_cat(left: date[], right: date[]) → date[]

Appends two arrays.

+		Immutable
array_cat(left: decimal[], right: decimal[]) → decimal[]

Appends two arrays.

+		Immutable
array_cat(left: float[], right: float[]) → float[]

Appends two arrays.

+		Immutable
array_cat(left: inet[], right: inet[]) → inet[]

Appends two arrays.

+		Immutable
array_cat(left: int[], right: int[]) → int[]

Appends two arrays.

+		Immutable
array_cat(left: interval[], right: interval[]) → interval[]

Appends two arrays.

+		Immutable
array_cat(left: string[], right: string[]) → string[]

Appends two arrays.

+		Immutable
array_cat(left: time[], right: time[]) → time[]

Appends two arrays.

+		Immutable
array_cat(left: timestamp[], right: timestamp[]) → timestamp[]

Appends two arrays.

+		Immutable
array_cat(left: timestamptz[], right: timestamptz[]) → timestamptz[]

Appends two arrays.

+		Immutable
array_cat(left: uuid[], right: uuid[]) → uuid[]

Appends two arrays.

+		Immutable
array_cat(left: anyenum[], right: anyenum[]) → anyenum[]

Appends two arrays.

+		Immutable
array_cat(left: box2d[], right: box2d[]) → box2d[]

Appends two arrays.

+		Immutable
array_cat(left: geography[], right: geography[]) → geography[]

Appends two arrays.

+		Immutable
array_cat(left: geometry[], right: geometry[]) → geometry[]

Appends two arrays.

+		Immutable
array_cat(left: jsonb[], right: jsonb[]) → jsonb[]

Appends two arrays.

+		Immutable
array_cat(left: ltree[], right: ltree[]) → ltree[]

Appends two arrays.

+		Immutable
array_cat(left: oid[], right: oid[]) → oid[]

Appends two arrays.

+		Immutable
array_cat(left: pg_lsn[], right: pg_lsn[]) → pg_lsn[]

Appends two arrays.

+		Immutable
array_cat(left: refcursor[], right: refcursor[]) → refcursor[]

Appends two arrays.

+		Immutable
array_cat(left: timetz[], right: timetz[]) → timetz[]

Appends two arrays.

+		Immutable
array_cat(left: tuple[], right: tuple[]) → tuple[]

Appends two arrays.

+		Immutable
array_cat(left: varbit[], right: varbit[]) → varbit[]

Appends two arrays.

+		Immutable
array_length(input: anyelement[], array_dimension: int) → int

Calculates the length of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_lower(input: anyelement[], array_dimension: int) → int

Calculates the minimum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_position(array: bool[], elem: bool) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bool[], elem: bool, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: bytes[], elem: bytes) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bytes[], elem: bytes, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: date[], elem: date) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: date[], elem: date, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: decimal[], elem: decimal) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: decimal[], elem: decimal, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: float[], elem: float) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: float[], elem: float, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: inet[], elem: inet) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: inet[], elem: inet, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: int[], elem: int) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: int[], elem: int, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: interval[], elem: interval) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: interval[], elem: interval, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: string[], elem: string) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: string[], elem: string, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: time[], elem: time) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: time[], elem: time, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timestamp[], elem: timestamp) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamp[], elem: timestamp, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: uuid[], elem: uuid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: uuid[], elem: uuid, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: anyenum[], elem: anyenum) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: anyenum[], elem: anyenum, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: box2d[], elem: box2d) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: box2d[], elem: box2d, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: geography[], elem: geography) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geography[], elem: geography, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: geometry[], elem: geometry) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geometry[], elem: geometry, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: jsonb[], elem: jsonb) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: jsonb[], elem: jsonb, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: ltree[], elem: ltree) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: ltree[], elem: ltree, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: oid[], elem: oid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: oid[], elem: oid, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: refcursor[], elem: refcursor) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: refcursor[], elem: refcursor, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timetz[], elem: timetz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timetz[], elem: timetz, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: tuple[], elem: tuple) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: tuple[], elem: tuple, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: varbit[], elem: varbit) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: varbit[], elem: varbit, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_positions(array: bool[], elem: bool) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: bytes[], elem: bytes) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: date[], elem: date) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: decimal[], elem: decimal) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: float[], elem: float) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: inet[], elem: inet) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: int[], elem: int) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: interval[], elem: interval) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: string[], elem: string) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: time[], elem: time) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamp[], elem: timestamp) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamptz[], elem: timestamptz) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: uuid[], elem: uuid) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: anyenum[], elem: anyenum) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: box2d[], elem: box2d) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geography[], elem: geography) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geometry[], elem: geometry) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: jsonb[], elem: jsonb) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: ltree[], elem: ltree) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: oid[], elem: oid) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: pg_lsn[], elem: pg_lsn) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: refcursor[], elem: refcursor) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timetz[], elem: timetz) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: tuple[], elem: tuple) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: varbit[], elem: varbit) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_prepend(elem: bool, array: bool[]) → bool[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: bytes, array: bytes[]) → bytes[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: date, array: date[]) → date[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: decimal, array: decimal[]) → decimal[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: float, array: float[]) → float[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: inet, array: inet[]) → inet[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: int, array: int[]) → int[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: interval, array: interval[]) → interval[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: string, array: string[]) → string[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: time, array: time[]) → time[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamp, array: timestamp[]) → timestamp[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamptz, array: timestamptz[]) → timestamptz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: uuid, array: uuid[]) → uuid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: anyenum, array: anyenum[]) → anyenum[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: box2d, array: box2d[]) → box2d[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geography, array: geography[]) → geography[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geometry, array: geometry[]) → geometry[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: jsonb, array: jsonb[]) → jsonb[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: ltree, array: ltree[]) → ltree[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: oid, array: oid[]) → oid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: pg_lsn, array: pg_lsn[]) → pg_lsn[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: refcursor, array: refcursor[]) → refcursor[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timetz, array: timetz[]) → timetz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: tuple, array: tuple[]) → tuple[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: varbit, array: varbit[]) → varbit[]

Prepends elem to array, returning the result.

+		Immutable
array_remove(array: bool[], elem: bool) → bool[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: bytes[], elem: bytes) → bytes[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: date[], elem: date) → date[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: decimal[], elem: decimal) → decimal[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: float[], elem: float) → float[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: inet[], elem: inet) → inet[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: int[], elem: int) → int[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: interval[], elem: interval) → interval[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: string[], elem: string) → string[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: time[], elem: time) → time[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamp[], elem: timestamp) → timestamp[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamptz[], elem: timestamptz) → timestamptz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: uuid[], elem: uuid) → uuid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: anyenum[], elem: anyenum) → anyenum[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: box2d[], elem: box2d) → box2d[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geography[], elem: geography) → geography[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geometry[], elem: geometry) → geometry[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: jsonb[], elem: jsonb) → jsonb[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: ltree[], elem: ltree) → ltree[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: oid[], elem: oid) → oid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: refcursor[], elem: refcursor) → refcursor[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timetz[], elem: timetz) → timetz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: tuple[], elem: tuple) → tuple[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: varbit[], elem: varbit) → varbit[]

Remove from array all elements equal to elem.

+		Immutable
array_replace(array: bool[], toreplace: bool, replacewith: bool) → bool[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: bytes[], toreplace: bytes, replacewith: bytes) → bytes[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: date[], toreplace: date, replacewith: date) → date[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: decimal[], toreplace: decimal, replacewith: decimal) → decimal[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: float[], toreplace: float, replacewith: float) → float[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: inet[], toreplace: inet, replacewith: inet) → inet[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: int[], toreplace: int, replacewith: int) → int[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: interval[], toreplace: interval, replacewith: interval) → interval[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: string[], toreplace: string, replacewith: string) → string[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: time[], toreplace: time, replacewith: time) → time[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamp[], toreplace: timestamp, replacewith: timestamp) → timestamp[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamptz[], toreplace: timestamptz, replacewith: timestamptz) → timestamptz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: uuid[], toreplace: uuid, replacewith: uuid) → uuid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: anyenum[], toreplace: anyenum, replacewith: anyenum) → anyenum[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: box2d[], toreplace: box2d, replacewith: box2d) → box2d[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geography[], toreplace: geography, replacewith: geography) → geography[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geometry[], toreplace: geometry, replacewith: geometry) → geometry[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: jsonb[], toreplace: jsonb, replacewith: jsonb) → jsonb[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: ltree[], toreplace: ltree, replacewith: ltree) → ltree[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: oid[], toreplace: oid, replacewith: oid) → oid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: pg_lsn[], toreplace: pg_lsn, replacewith: pg_lsn) → pg_lsn[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: refcursor[], toreplace: refcursor, replacewith: refcursor) → refcursor[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timetz[], toreplace: timetz, replacewith: timetz) → timetz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: tuple[], toreplace: tuple, replacewith: tuple) → tuple[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: varbit[], toreplace: varbit, replacewith: varbit) → varbit[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_to_string(input: anyelement[], delim: string) → string

Join an array into a string with a delimiter.

+		Stable
array_to_string(input: anyelement[], delimiter: string, null: string) → string

Join an array into a string with a delimiter, replacing NULLs with a null string.

+		Stable
array_upper(input: anyelement[], array_dimension: int) → int

Calculates the maximum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
cardinality(input: anyelement[]) → int

Calculates the number of elements contained in input

+		Immutable
jsonb_array_to_string_array(input: jsonb) → string[]

Convert a JSONB array into a string array.

+		Immutable
string_to_array(str: string, delimiter: string) → string[]

Split a string into components on a delimiter.

+		Immutable
string_to_array(str: string, delimiter: string, null: string) → string[]

Split a string into components on a delimiter with a specified string to consider NULL.

+		Immutable
+ +### BOOL functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Matches case insensetively unescaped with pattern using escape as an escape token.

+		Immutable
inet_contained_by_or_equals(val: inet, container: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_contains_or_equals(container: inet, val: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_same_family(val: inet, val: inet) → bool

Checks if two IP addresses are of the same IP family.

+		Immutable
like_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
not_ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches case insensetively with pattern using escape as an escape token.

+		Immutable
not_like_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
not_similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
+ +### Comparison functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
greatest(anyelement...) → anyelement

Returns the element with the greatest value.

+		Immutable
least(anyelement...) → anyelement

Returns the element with the lowest value.

+		Immutable
num_nonnulls(any...) → int

Returns the number of nonnull arguments.

+		Immutable
num_nulls(any...) → int

Returns the number of null arguments.

+		Immutable
+ +### Cryptographic functions + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crypt(password: string, salt: string) → string

Generates a hash based on a password and salt. The hash algorithm and number of rounds if applicable are encoded in the salt.

+		Immutable
decrypt(data: bytes, key: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
decrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
digest(data: bytes, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
digest(data: string, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
encrypt(data: bytes, key: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
encrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
gen_random_bytes(count: int) → bytes

Returns count cryptographically strong random bytes. At most 1024 bytes can be extracted at a time.

+		Volatile
gen_salt(type: string) → string

Generates a salt for input into the crypt function using the default number of rounds.

+		Volatile
gen_salt(type: string, iter_count: int) → string

Generates a salt for input into the crypt function using iter_count number of rounds.

+		Volatile
hmac(data: bytes, key: bytes, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
hmac(data: string, key: string, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
+ +### DECIMAL functions + + + + + +
Function → ReturnsDescriptionVolatility
hlc_to_timestamp(hlc: decimal) → timestamptz

Returns a TimestampTZ representation of a CockroachDB HLC in decimal form.

+

Note that a TimestampTZ has less precision than a CockroachDB HLC. It is intended as +a convenience function to display HLCs in a print-friendly form. Use the decimal +value if you rely on the HLC for accuracy.

+		Immutable
+ +### Date and time functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
age(end: timestamptz, begin: timestamptz) → interval

Calculates the interval between begin and end, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use the timestamptz subtraction operator.

+		Immutable
age(val: timestamptz) → interval

Calculates the interval between val and the current time, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use now() - timestamptz.

+		Stable
clock_timestamp() → timestamp

Returns the current system time on one of the cluster nodes.

+		Volatile
clock_timestamp() → timestamptz

Returns the current system time on one of the cluster nodes.

+		Volatile
current_date() → date

Returns the date of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_timestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
date_part(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
date_part(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
date_trunc(element: string, input: date) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: interval) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: time) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero.

+

Compatible elements: hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamp) → timestamp

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamptz) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: timestamptz, timezone: string) → timestamptz

Truncates input to precision element in the specified timezone. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
experimental_follower_read_timestamp() → timestamptz

Same as follower_read_timestamp. This name is deprecated.

+		Volatile
experimental_strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
extract(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
extract(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
extract_duration(element: string, input: interval) → int

Extracts element from input. +Compatible elements: hour, minute, second, millisecond, microsecond. +This is deprecated in favor of extract which supports duration.

+		Immutable
follower_read_timestamp() → timestamptz

Returns a timestamp which is very likely to be safe to perform +against a follower replica.

+

This function is intended to be used with an AS OF SYSTEM TIME clause to perform +historical reads against a time which is recent but sufficiently old for reads +to be performed against the closest replica as opposed to the currently +leaseholder for a given range.

+

Note that this function requires an enterprise license on a CCL distribution to +return a result that is less likely the closest replica. It is otherwise +hardcoded as -4.8s from the statement time, which may not result in reading from the +nearest replica.

+		Volatile
localtimestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
make_date(year: int, month: int, day: int) → date

Create date (formatted according to ISO 8601) from year, month, and day fields (negative years signify BC).

+		Immutable
make_timestamp(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamp

Create timestamp (formatted according to ISO 8601) from year, month, day, hour, minute, and seconds fields (negative years signify BC).

+		Immutable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float, timezone: string) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
now() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
overlaps(s1: date, e1: date, s1: date, e2: date) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: date, e1: interval, s1: date, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: interval, s1: time, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: time, s1: time, e2: time) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: interval, s1: timestamp, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: timestamp, s1: timestamp, e2: timestamp) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamptz, e1: interval, s1: timestamptz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Stable
overlaps(s1: timestamptz, e1: timestamptz, s1: timestamptz, e2: timestamptz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: interval, s1: timetz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: timetz, s1: timetz, e2: timetz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
statement_timestamp() → timestamp

Returns the start time of the current statement.

+		Stable
statement_timestamp() → timestamptz

Returns the start time of the current statement.

+		Stable
strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
timeofday() → string

Returns the current system time on one of the cluster nodes as a string.

+		Stable
timezone(timezone: string, time: time) → timetz

Treat given time without time zone as located in the specified time zone.

+		Stable
timezone(timezone: string, timestamp: timestamp) → timestamptz

Treat given time stamp without time zone as located in the specified time zone.

+		Immutable
timezone(timezone: string, timestamptz: timestamptz) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Immutable
timezone(timezone: string, timestamptz_string: string) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Stable
timezone(timezone: string, timetz: timetz) → timetz

Convert given time with time zone to the new time zone.

+		Stable
to_char(date: date) → string

Convert an date to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(date: date, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_char(interval: interval) → string

Convert an interval to a string assuming the Postgres IntervalStyle.

+		Immutable
to_char(interval: interval, format: string) → string

Convert an interval to a string using the given format.

+		Stable
to_char(timestamp: timestamp) → string

Convert an timestamp to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(timestamp: timestamp, format: string) → string

Convert an timestamp to a string using the given format.

+		Stable
to_char(timestamptz: timestamptz, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_timestamp(timestamp: float) → timestamptz

Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to timestamp with time zone.

+		Immutable
transaction_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
with_max_staleness(max_staleness: interval) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_max_staleness(max_staleness: interval, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
+ +### Enum functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
enum_first(val: anyenum) → anyenum

Returns the first value of the input enum type.

+		Stable
enum_last(val: anyenum) → anyenum

Returns the last value of the input enum type.

+		Stable
enum_range(lower: anyenum, upper: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array between the two arguments (inclusive).

+		Stable
enum_range(val: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array.

+		Stable
+ +### FLOAT functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abs(val: decimal) → decimal

Calculates the absolute value of val.

+		Immutable
abs(val: float) → float

Calculates the absolute value of val.

+		Immutable
abs(val: int) → int

Calculates the absolute value of val.

+		Immutable
acos(val: float) → float

Calculates the inverse cosine of val.

+		Immutable
acosd(val: float) → float

Calculates the inverse cosine of val with the result in degrees

+		Immutable
acosh(val: float) → float

Calculates the inverse hyperbolic cosine of val.

+		Immutable
asin(val: float) → float

Calculates the inverse sine of val.

+		Immutable
asind(val: float) → float

Calculates the inverse sine of val with the result in degrees.

+		Immutable
asinh(val: float) → float

Calculates the inverse hyperbolic sine of val.

+		Immutable
atan(val: float) → float

Calculates the inverse tangent of val.

+		Immutable
atan2(x: float, y: float) → float

Calculates the inverse tangent of x/y.

+		Immutable
atan2d(x: float, y: float) → float

Calculates the inverse tangent of x/y with the result in degrees

+		Immutable
atand(val: float) → float

Calculates the inverse tangent of val with the result in degrees.

+		Immutable
atanh(val: float) → float

Calculates the inverse hyperbolic tangent of val.

+		Immutable
cbrt(val: decimal) → decimal

Calculates the cube root (∛) of val.

+		Immutable
cbrt(val: float) → float

Calculates the cube root (∛) of val.

+		Immutable
ceil(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
cos(val: float) → float

Calculates the cosine of val.

+		Immutable
cosd(val: float) → float

Calculates the cosine of val where val is in degrees.

+		Immutable
cosh(val: float) → float

Calculates the hyperbolic cosine of val.

+		Immutable
cot(val: float) → float

Calculates the cotangent of val.

+		Immutable
cotd(val: float) → float

Calculates the cotangent of val where val is in degrees.

+		Immutable
degrees(val: float) → float

Converts val as a radian value to a degree value.

+		Immutable
div(x: decimal, y: decimal) → decimal

Calculates the integer quotient of x/y.

+		Immutable
div(x: float, y: float) → float

Calculates the integer quotient of x/y.

+		Immutable
div(x: int, y: int) → int

Calculates the integer quotient of x/y.

+		Immutable
exp(val: decimal) → decimal

Calculates e ^ val.

+		Immutable
exp(val: float) → float

Calculates e ^ val.

+		Immutable
floor(val: decimal) → decimal

Calculates the largest integer not greater than val.

+		Immutable
floor(val: float) → float

Calculates the largest integer not greater than val.

+		Immutable
floor(val: int) → float

Calculates the largest integer not greater than val.

+		Immutable
isnan(val: decimal) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
isnan(val: float) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
ln(val: decimal) → decimal

Calculates the natural log of val.

+		Immutable
ln(val: float) → float

Calculates the natural log of val.

+		Immutable
log(b: decimal, x: decimal) → decimal

Calculates the base b log of val.

+		Immutable
log(b: float, x: float) → float

Calculates the base b log of val.

+		Immutable
log(val: decimal) → decimal

Calculates the base 10 log of val.

+		Immutable
log(val: float) → float

Calculates the base 10 log of val.

+		Immutable
mod(x: decimal, y: decimal) → decimal

Calculates x%y.

+		Immutable
mod(x: float, y: float) → float

Calculates x%y.

+		Immutable
mod(x: int, y: int) → int

Calculates x%y.

+		Immutable
pi() → float

Returns the value for pi (3.141592653589793).

+		Immutable
pow(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
pow(x: float, y: float) → float

Calculates x^y.

+		Immutable
pow(x: int, y: int) → int

Calculates x^y.

+		Immutable
power(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
power(x: float, y: float) → float

Calculates x^y.

+		Immutable
power(x: int, y: int) → int

Calculates x^y.

+		Immutable
radians(val: float) → float

Converts val as a degree value to a radians value.

+		Immutable
random() → float

Returns a random floating-point number between 0 (inclusive) and 1 (exclusive). Note that the value contains at most 53 bits of randomness.

+		Volatile
round(input: decimal, decimal_accuracy: int) → decimal

Keeps decimal_accuracy number of figures to the right of the zero position in input using half away from zero rounding. If decimal_accuracy is not in the range -2^31…(2^31-1), the results are undefined.

+		Immutable
round(input: float, decimal_accuracy: int) → float

Keeps decimal_accuracy number of figures to the right of the zero position in input using half to even (banker’s) rounding.

+		Immutable
round(val: decimal) → decimal

Rounds val to the nearest integer, half away from zero: round(+/-2.4) = +/-2, round(+/-2.5) = +/-3.

+		Immutable
round(val: float) → float

Rounds val to the nearest integer using half to even (banker’s) rounding.

+		Immutable
setseed(seed: float) → void

Sets the seed for subsequent random() calls in this session (value between -1.0 and 1.0, inclusive). There are no guarantees as to how this affects the seed of random() calls that appear in the same query as setseed().

+		Volatile
sign(val: decimal) → decimal

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: float) → float

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: int) → int

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sin(val: float) → float

Calculates the sine of val.

+		Immutable
sind(val: float) → float

Calculates the sine of val where val is in degrees.

+		Immutable
sinh(val: float) → float

Calculates the hyperbolic sine of val.

+		Immutable
sqrt(val: decimal) → decimal

Calculates the square root of val.

+		Immutable
sqrt(val: float) → float

Calculates the square root of val.

+		Immutable
tan(val: float) → float

Calculates the tangent of val.

+		Immutable
tand(val: float) → float

Calculates the tangent of val where val is in degrees.

+		Immutable
tanh(val: float) → float

Calculates the hyperbolic tangent of val.

+		Immutable
trunc(val: decimal) → decimal

Truncates the decimal values of val.

+		Immutable
trunc(val: decimal, scale: int) → decimal

Truncate val to scale decimal places

+		Immutable
trunc(val: float) → float

Truncates the decimal values of val.

+		Immutable
+ +### Full Text Search functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
phraseto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The <-> operator is inserted between each token in the input.

+		Immutable
phraseto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The <-> operator is inserted between each token in the input.

+		Stable
plainto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The & operator is inserted between each token in the input.

+		Immutable
plainto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The & operator is inserted between each token in the input.

+		Stable
to_tsquery(config: string, text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the specified configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Immutable
to_tsquery(text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the default configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Stable
to_tsvector(config: string, text: string) → tsvector

Converts text to a tsvector, normalizing words according to the specified configuration. Position information is included in the result.

+		Immutable
to_tsvector(text: string) → tsvector

Converts text to a tsvector, normalizing words according to the default configuration. Position information is included in the result.

+		Stable
ts_parse(parser_name: string, document: string) → tuple{int AS tokid, string AS token}

ts_parse parses the given document and returns a series of records, one for each token produced by parsing. Each record includes a tokid showing the assigned token type and a token which is the text of the token.

+		Stable
ts_rank(vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
+ +### Fuzzy String Matching functions + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
levenshtein(source: string, target: string) → int

Calculates the Levenshtein distance between two strings. Maximum input length is 255 characters.

+		Immutable
levenshtein(source: string, target: string, ins_cost: int, del_cost: int, sub_cost: int) → int

Calculates the Levenshtein distance between two strings. The cost parameters specify how much to charge for each edit operation. Maximum input length is 255 characters.

+		Immutable
levenshtein_less_equal(source: string, target: string, ins_cost: int, del_cost: int, sub_cost: int, max_d: int) → int

Calculates the Levenshtein distance between two strings. The cost parameters specify how much to charge for each edit operation. If actual distance is less or equal then max_d, then it returns the distance. Otherwise this function returns a value greater than max_d. The maximum length of the input strings is 255 characters.

+		Immutable
levenshtein_less_equal(source: string, target: string, max_d: int) → int

Calculates the Levenshtein distance between two strings. If actual distance is less or equal then max_d, then it returns the distance. Otherwise this function returns a value greater than max_d. The maximum length of the input strings is 255 characters.

+		Immutable
metaphone(source: string, max_output_length: int) → string

Convert a string to its Metaphone code. Maximum input length is 255 characters

+		Immutable
soundex(source: string) → string

Convert a string to its Soundex code.

+		Immutable
+ +### ID generation functions + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
experimental_uuid_v4() → bytes

Returns a UUID.

+		Volatile
gen_random_ulid() → uuid

Generates a random ULID and returns it as a value of UUID type.

+		Volatile
gen_random_uuid() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
unique_rowid() → int

Returns a unique ID used by CockroachDB to generate unique row IDs if a Primary Key isn’t defined for the table. The value is a combination of the insert timestamp and the ID of the node executing the statement, which guarantees this combination is globally unique. However, there can be gaps and the order is not completely guaranteed.

+		Volatile
unordered_unique_rowid() → int

Returns a unique ID. The value is a combination of the insert timestamp (bit-reversed) and the ID of the node executing the statement, which guarantees this combination is globally unique. The way it is generated is statistically likely to not have any ordering relative to previously generated values.

+		Volatile
uuid_generate_v1() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. To avoid exposing the server’s real MAC address, this uses a random MAC address and a timestamp. Essentially, this is an alias for uuid_generate_v1mc.

+		Volatile
uuid_generate_v1mc() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. This uses a random MAC address and a timestamp.

+		Volatile
uuid_generate_v3(namespace: uuid, name: string) → uuid

Generates a version 3 UUID in the given namespace using the specified input name, with md5 as the hashing method. The namespace should be one of the special constants produced by the uuid_ns_*() functions.

+		Immutable
uuid_generate_v4() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
uuid_generate_v5(namespace: uuid, name: string) → uuid

Generates a version 5 UUID in the given namespace using the specified input name. This is similar to a version 3 UUID, except it uses SHA-1 for hashing.

+		Immutable
uuid_nil() → uuid

Returns a nil UUID constant.

+		Immutable
uuid_ns_dns() → uuid

Returns a constant designating the DNS namespace for UUIDs.

+		Immutable
uuid_ns_oid() → uuid

Returns a constant designating the ISO object identifier (OID) namespace for UUIDs. These are unrelated to the OID type used internally in the database.

+		Immutable
uuid_ns_url() → uuid

Returns a constant designating the URL namespace for UUIDs.

+		Immutable
uuid_ns_x500() → uuid

Returns a constant designating the X.500 distinguished name (DN) namespace for UUIDs.

+		Immutable
uuid_v4() → bytes

Returns a UUID.

+		Volatile
+ +### INET functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abbrev(val: inet) → string

Converts the combined IP address and prefix length to an abbreviated display format as text.For INET types, this will omit the prefix length if it’s not the default (32 or IPv4, 128 for IPv6)

+

For example, abbrev('192.168.1.2/24') returns '192.168.1.2/24'

+		Immutable
broadcast(val: inet) → inet

Gets the broadcast address for the network address represented by the value.

+

For example, broadcast('192.168.1.2/24') returns '192.168.1.255/24'

+		Immutable
family(val: inet) → int

Extracts the IP family of the value; 4 for IPv4, 6 for IPv6.

+

For example, family('::1') returns 6

+		Immutable
host(val: inet) → string

Extracts the address part of the combined address/prefixlen value as text.

+

For example, host('192.168.1.2/16') returns '192.168.1.2'

+		Immutable
hostmask(val: inet) → inet

Creates an IP host mask corresponding to the prefix length in the value.

+

For example, hostmask('192.168.1.2/16') returns '0.0.255.255'

+		Immutable
masklen(val: inet) → int

Retrieves the prefix length stored in the value.

+

For example, masklen('192.168.1.2/16') returns 16

+		Immutable
netmask(val: inet) → inet

Creates an IP network mask corresponding to the prefix length in the value.

+

For example, netmask('192.168.1.2/16') returns '255.255.0.0'

+		Immutable
set_masklen(val: inet, prefixlen: int) → inet

Sets the prefix length of val to prefixlen.

+

For example, set_masklen('192.168.1.2', 16) returns '192.168.1.2/16'.

+		Immutable
+ +### INT functions + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crc32c(bytes...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32c(string...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32ieee(bytes...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
crc32ieee(string...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
fnv32(bytes...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32(string...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32a(bytes...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv32a(string...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64(bytes...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64(string...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64a(bytes...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64a(string...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
width_bucket(operand: decimal, b1: decimal, b2: decimal, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2. Returns 0 or count+1 for an input outside that range.

+		Immutable
width_bucket(operand: int, b1: int, b2: int, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2.

+		Immutable
width_bucket(operand: anyelement, thresholds: anyelement[]) → int

return the bucket number to which operand would be assigned given an array listing the lower bounds of the buckets; returns 0 for an input less than the first lower bound; the thresholds array must be sorted, smallest first, or unexpected results will be obtained

+		Immutable
+ +### JSONB functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_to_json(array: anyelement[]) → jsonb

Returns the array as JSON or JSONB.

+		Stable
array_to_json(array: anyelement[], pretty_bool: bool) → jsonb

Returns the array as JSON or JSONB.

+		Stable
json_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
json_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
json_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
json_build_array(any...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
json_build_object(any...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
json_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
json_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
json_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
json_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
json_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
json_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
json_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
json_remove_path(val: jsonb, path: string[]) → jsonb

Remove the specified path from the JSON object.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
json_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
json_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
json_valid(string: string) → bool

Returns whether the given string is a valid JSON or not

+		Immutable
jsonb_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
jsonb_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
jsonb_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
jsonb_build_array(any...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
jsonb_build_object(any...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
jsonb_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
jsonb_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
jsonb_exists_any(json: jsonb, array: string[]) → bool

Returns whether any of the strings in the text array exist as top-level keys or array elements

+		Immutable
jsonb_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments. new_val will be inserted before path target.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb, insert_after: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If insert_after is true (default is false), new_val will be inserted after path target.

+		Immutable
jsonb_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
jsonb_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
jsonb_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
jsonb_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
jsonb_pretty(val: jsonb) → string

Returns the given JSON value as a STRING indented and with newlines.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
jsonb_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
jsonb_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
row_to_json(row: tuple) → jsonb

Returns the row as a JSON object.

+		Stable
to_json(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
to_jsonb(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
+ +### Jsonpath functions + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
jsonb_path_exists(target: jsonb, path: jsonpath) → bool

Checks whether the JSON path returns any item for the specified JSON value.

+		Immutable
jsonb_path_exists(target: jsonb, path: jsonpath, vars: jsonb) → bool

Checks whether the JSON path returns any item for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named +values to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_exists(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → bool

Checks whether the JSON path returns any item for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named +values to be substituted into the jsonpath expression. If the silent +argument is true, the function suppresses the following errors: +missing object field or array element, unexpected JSON item type, +datetime and numeric errors.

+		Immutable
jsonb_path_match(target: jsonb, path: jsonpath) → bool

Returns the SQL boolean result of a JSON path predicate check +for the specified JSON value. (This is useful only with predicate check +expressions, not SQL-standard JSON path expressions, since it will +either fail or return NULL if the path result is not a single boolean +value.)

+		Immutable
jsonb_path_match(target: jsonb, path: jsonpath, vars: jsonb) → bool

Returns the SQL boolean result of a JSON path predicate check +for the specified JSON value. (This is useful only with predicate check +expressions, not SQL-standard JSON path expressions, since it will +either fail or return NULL if the path result is not a single boolean +value.) The vars argument must be a JSON object, and its fields provide +named values to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_match(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → bool

Returns the SQL boolean result of a JSON path predicate check +for the specified JSON value. (This is useful only with predicate check +expressions, not SQL-standard JSON path expressions, since it will +either fail or return NULL if the path result is not a single boolean +value.) The vars argument must be a JSON object, and its fields provide +named values to be substituted into the jsonpath expression. If the +silent argument is true, the function suppresses the following errors: +missing object field or array element, unexpected JSON item type, +datetime and numeric errors.

+		Immutable
jsonb_path_query(target: jsonb, path: jsonpath) → jsonb

Returns all JSON items returned by the JSON path for the specified JSON value.

+		Immutable
jsonb_path_query(target: jsonb, path: jsonpath, vars: jsonb) → jsonb

Returns all JSON items returned by the JSON path for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_query(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → jsonb

Returns all JSON items returned by the JSON path for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression. If the silent argument is true, +the function suppresses the following errors: missing object field or array +element, unexpected JSON item type, datetime and numeric errors.

+		Immutable
jsonb_path_query_array(target: jsonb, path: jsonpath) → jsonb

Returns all JSON items returned by the JSON path for the +specified JSON value, as a JSON array.

+		Immutable
jsonb_path_query_array(target: jsonb, path: jsonpath, vars: jsonb) → jsonb

Returns all JSON items returned by the JSON path for the +specified JSON value, as a JSON array. The vars argument must be a +JSON object, and its fields provide named values to be substituted +into the jsonpath expression.

+		Immutable
jsonb_path_query_array(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → jsonb

Returns all JSON items returned by the JSON path for the +specified JSON value, as a JSON array. The vars argument must be a +JSON object, and its fields provide named values to be substituted +into the jsonpath expression. If the silent argument is true, the +function suppresses the following errors: missing object field or +array element, unexpected JSON item type, datetime and numeric errors.

+		Immutable
jsonb_path_query_first(target: jsonb, path: jsonpath) → jsonb

Returns the first JSON item returned by the JSON path for the +specified JSON value, or NULL if there are no results.

+		Immutable
jsonb_path_query_first(target: jsonb, path: jsonpath, vars: jsonb) → jsonb

Returns the first JSON item returned by the JSON path for the +specified JSON value, or NULL if there are no results. The vars +argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_query_first(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → jsonb

Returns the first JSON item returned by the JSON path for the +specified JSON value, or NULL if there are no results. The vars +argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression. If the silent argument is true, the +function suppresses the following errors: missing object field or +array element, unexpected JSON item type, datetime and numeric errors.

+		Immutable
+ +### LTree functions + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
index(a: ltree, b: ltree) → int

position of first occurrence of b in a; -1 if not found

+		Immutable
index(a: ltree, b: ltree, offset: int) → int

position of first occurrence of b in a, starting at offset; -1 if not found

+		Immutable
lca(ltree, ltree, ltree...) → ltree

lowest common ancestor, i.e., longest common prefix of paths

+		Immutable
lca(ltree[]: ltree[]) → ltree

lowest common ancestor, i.e., longest common prefix of paths

+		Immutable
ltree2text(ltree: ltree) → string

cast ltree to text

+		Immutable
nlevel(ltree: ltree) → int

number of labels in path ltree

+		Immutable
subltree(ltree: ltree, start: int, end: int) → ltree

subpath of ltree from position start to position end-1 (counting from 0)

+		Immutable
subpath(ltree: ltree, offset: int) → ltree

subpath of ltree starting at position offset, extending to end of path. If offset is negative, subpath starts that far from the end of the path.

+		Immutable
subpath(ltree: ltree, offset: int, length: int) → ltree

subpath of ltree starting at position offset, length length. If offset is negative, subpath starts that far from the end of the path. If length is negative, leaves that many labels off the end of the path.

+		Immutable
text2ltree(text: string) → ltree

cast text to ltree

+		Immutable
+ +### Multi-region functions + + + + + + + +
Function → ReturnsDescriptionVolatility
default_to_database_primary_region(val: string) → string

Returns the given region if the region has been added to the current database. +Otherwise, this will return the primary region of the current database. +This will error if the current database is not a multi-region database.

+		Stable
gateway_region() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
rehome_row() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
+ +### PGVector functions + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cosine_distance(v1: vector, v2: vector) → float

Returns the cosine distance between the two vectors.

+		Immutable
inner_product(v1: vector, v2: vector) → float

Returns the inner product between the two vectors.

+		Immutable
l1_distance(v1: vector, v2: vector) → float

Returns the Manhattan distance between the two vectors.

+		Immutable
l2_distance(v1: vector, v2: vector) → float

Returns the Euclidean distance between the two vectors.

+		Immutable
vector_dims(vector: vector) → int

Returns the number of the dimensions in the vector.

+		Immutable
vector_norm(vector: vector) → float

Returns the Euclidean norm of the vector.

+		Immutable
+ +### STRING[] functions + + + + + + +
Function → ReturnsDescriptionVolatility
regexp_split_to_array(string: string, pattern: string) → string[]

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_array(string: string, pattern: string, flags: string) → string[]

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
+ +### Sequence functions + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
currval(sequence_name: string) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
currval(sequence_name: regclass) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
lastval() → int

Return value most recently obtained with nextval in this session.

+		Volatile
nextval(sequence_name: string) → int

Advances the given sequence and returns its new value.

+		Volatile
nextval(sequence_name: regclass) → int

Advances the given sequence and returns its new value.

+		Volatile
setval(sequence_name: string, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: string, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
setval(sequence_name: regclass, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: regclass, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
+ +### Set-returning functions + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
aclexplode(aclitems: string[]) → tuple{oid AS grantor, oid AS grantee, string AS privilege_type, bool AS is_grantable}

Produces a virtual table containing aclitem stuff (returns no rows as this feature is unsupported in CockroachDB)

+		Stable
generate_series(start: int, end: int) → int

Produces a virtual table containing the integer values from start to end, inclusive.

+		Immutable
generate_series(start: int, end: int, step: int) → int

Produces a virtual table containing the integer values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamp, end: timestamp, step: interval) → timestamp

Produces a virtual table containing the timestamp values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamptz, end: timestamptz, step: interval) → timestamptz

Produces a virtual table containing the timestampTZ values from start to end, inclusive, by increment of step.

+		Immutable
generate_subscripts(array: anyelement[]) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int, reverse: bool) → int

Returns a series comprising the given array’s subscripts.

+

When reverse is true, the series is returned in reverse order.

+		Immutable
information_schema._pg_expandarray(input: anyelement[]) → tuple{anyelement AS x, int AS n}

Returns the input array as a set of rows with an index

+		Immutable
json_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
json_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
json_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
jsonb_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
jsonb_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
jsonb_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
pg_get_keywords() → tuple{string AS word, string AS catcode, string AS catdesc}

Produces a virtual table containing the keywords known to the SQL parser.

+		Immutable
pg_options_to_table(options: string[]) → tuple{string AS option_name, string AS option_value}

Converts the options array format to a table.

+		Stable
regexp_split_to_table(string: string, pattern: string) → string

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_table(string: string, pattern: string, flags: string) → string

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
unnest(anyelement[], anyelement[], anyelement[]...) → tuple{anyelement AS unnest, anyelement AS unnest, anyelement AS unnest}

Returns the input arrays as a set of rows

+		Immutable
unnest(input: anyelement[]) → anyelement

Returns the input array as a set of rows

+		Immutable
workload_index_recs() → tuple{string AS index_rec, bytes[] AS fingerprint_ids}

Returns index recommendations and the fingerprint ids that the indexes will impact

+		Immutable
workload_index_recs(timestamptz: timestamptz) → tuple{string AS index_rec, bytes[] AS fingerprint_ids}

Returns index recommendations and the fingerprint ids that the indexes will impact

+		Immutable
+ +### Spatial functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
_st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
geometrytype(geometry: geometry) → string

Returns the type of geometry as a string.

+

This function utilizes the GEOS module.

+		Immutable
geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
postgis_addbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_dropbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_extensions_upgrade() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_full_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_geos_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_getbbox(geometry: geometry) → box2d

Returns a box2d encapsulating the given Geometry.

+		Immutable
postgis_hasbbox(geometry: geometry) → bool

Returns whether a given Geometry has a bounding box. False for points and empty geometries; always true otherwise.

+		Immutable
postgis_lib_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_lib_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_liblwgeom_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_libxml_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_proj_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_installed() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_released() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_wagyu_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
st_3dlength(geometry: geometry) → float

Returns the 3-dimensional or 2-dimensional length of the geometry.

+

Note ST_3DLength is only valid for LineString or MultiLineString. +For 2-D lines it will return the 2-D length (same as ST_Length and ST_Length2D)

+

This function utilizes the GEOS module.

+		Immutable
st_addmeasure(geometry: geometry, start: float, end: float) → geometry

Returns a copy of a LineString or MultiLineString with measure coordinates linearly interpolated between the specified start and end values. Any existing M coordinates will be overwritten.

+		Immutable
st_addpoint(line_string: geometry, point: geometry) → geometry

Adds a Point to the end of a LineString.

+		Immutable
st_addpoint(line_string: geometry, point: geometry, index: int) → geometry

Adds a Point to a LineString at the given 0-based index (-1 to append).

+		Immutable
st_affine(geometry: geometry, a: float, b: float, c: float, d: float, e: float, f: float, g: float, h: float, i: float, x_off: float, y_off: float, z_off: float) → geometry

Applies a 3D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b c x_off \ / x
+| d e f y_off | | y | +| g h i z_off | | z | +\ 0 0 0 1 / \ 0 /

+		Immutable
st_affine(geometry: geometry, a: float, b: float, d: float, e: float, x_off: float, y_off: float) → geometry

Applies a 2D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b x_off \ / x
+| d e y_off | | y | +\ 0 0 1 / \ 0 /

+		Immutable
st_angle(line1: geometry, line2: geometry) → float

Returns the clockwise angle between two LINESTRING geometries, treating them as vectors between their start- and endpoints. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry) → float

Returns the clockwise angle between the vectors formed by point2,point1 and point2,point3. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry, point4: geometry) → float

Returns the clockwise angle between the vectors formed by point1,point2 and point3,point4. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_area(geography: geography) → float

Returns the area of the given geography in meters^2. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geography: geography, use_spheroid: bool) → float

Returns the area of the given geography in meters^2.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_area(geometry_str: string) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_area2d(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_asbinary(geography: geography) → bytes

Returns the WKB representation of a given Geography.

+		Immutable
st_asbinary(geography: geography, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asbinary(geometry: geometry) → bytes

Returns the WKB representation of a given Geometry.

+		Immutable
st_asbinary(geometry: geometry, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asencodedpolyline(geometry: geometry) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Preserves 5 decimal places.

+		Immutable
st_asencodedpolyline(geometry: geometry, precision: int4) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+		Immutable
st_asewkb(geography: geography) → bytes

Returns the EWKB representation of a given Geography.

+		Immutable
st_asewkb(geometry: geometry) → bytes

Returns the EWKB representation of a given Geometry.

+		Immutable
st_asewkt(geography: geography) → string

Returns the EWKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_asewkt(geography: geography, max_decimal_digits: int) → string

Returns the EWKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry: geometry) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_asewkt(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry_str: string) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asewkt(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geography: geography) → string

Returns the GeoJSON representation of a given Geography. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option (default for Geography)
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326
    • +
+		Immutable
st_asgeojson(geometry: geometry) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+		Immutable
st_asgeojson(geometry_str: string) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(row: tuple) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(row: tuple, geo_column: string) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. Coordinates have a maximum of 9 decimal digits.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int, pretty: bool) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value. Output will be pretty printed in JSON if pretty is true.

+		Stable
st_ashexewkb(geography: geography) → string

Returns the EWKB representation in hex of a given Geography.

+		Immutable
st_ashexewkb(geography: geography, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexewkb(geometry: geometry) → string

Returns the EWKB representation in hex of a given Geometry.

+		Immutable
st_ashexewkb(geometry: geometry, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexwkb(geography: geography) → string

Returns the WKB representation in hex of a given Geography.

+		Immutable
st_ashexwkb(geometry: geometry) → string

Returns the WKB representation in hex of a given Geometry.

+		Immutable
st_askml(geography: geography) → string

Returns the KML representation of a given Geography.

+		Immutable
st_askml(geometry: geometry) → string

Returns the KML representation of a given Geometry.

+		Immutable
st_askml(geometry_str: string) → string

Returns the KML representation of a given Geometry.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping. +Uses 4096 as the tile extent size in tile coordinate space.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int, clip: bool) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds if required.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry can be transformed, and clipped if required.

+		Immutable
st_astext(geography: geography) → string

Returns the WKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_astext(geography: geography, max_decimal_digits: int) → string

Returns the WKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry: geometry) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_astext(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry_str: string) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astext(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int, precision_m: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_azimuth(geography_a: geography, geography_b: geography) → float

Returns the azimuth in radians of the segment defined by the given point geographies, or NULL if the two points are coincident. It is solved using the Inverse geodesic problem.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_azimuth(geometry_a: geometry, geometry_b: geometry) → float

Returns the azimuth in radians of the segment defined by the given point geometries, or NULL if the two points are coincident.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+		Immutable
st_bdpolyfromtext(str: string, srid: int) → geometry

Returns a Polygon from multilinestring WKT with a SRID. If the input is not a multilinestring an error will be thrown.

+		Immutable
st_boundary(geometry: geometry) → geometry

Returns the closure of the combinatorial boundary of this Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_box2dfromgeohash(geohash: string) → box2d

Return a Box2D from a GeoHash string with max precision.

+		Immutable
st_box2dfromgeohash(geohash: string, precision: int) → box2d

Return a Box2D from a GeoHash string with supplied precision.

+		Immutable
st_buffer(geography: geography, distance: float) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, buffer_style_params: string) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, quad_segs: int) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geometry: geometry, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry_str: string, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_centroid(geography: geography) → geography

Returns the centroid of given geography. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geography: geography, use_spheroid: bool) → geography

Returns the centroid of given geography.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geometry: geometry) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_centroid(geometry_str: string) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_clipbybox2d(geometry: geometry, box2d: box2d) → geometry

Clips the geometry to conform to the bounding box specified by box2d.

+		Immutable
st_closestpoint(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the 2-dimensional point on geometry_a that is closest to geometry_b. This is the first point of the shortest line.

+		Immutable
st_collectionextract(geometry: geometry, type: int) → geometry

Given a collection, returns a multitype consisting only of elements of the specified type. If there are no elements of the given type, an EMPTY geometry is returned. Types are specified as 1=POINT, 2=LINESTRING, 3=POLYGON - other types are not supported.

+		Immutable
st_collectionhomogenize(geometry: geometry) → geometry

Returns the “simplest” representation of a collection’s contents. Collections of a single type will be returned as an appopriate multitype, or a singleton if it only contains a single geometry.

+		Immutable
st_combinebbox(box2d: box2d, geometry: geometry) → box2d

Combines the current bounding box with the bounding box of the Geometry.

+		Immutable
st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_convexhull(geometry: geometry) → geometry

Returns a geometry that represents the Convex Hull of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_coorddim(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_difference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the difference of two Geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_dimension(geometry: geometry) → int

Returns the number of topological dimensions of a given Geometry.

+		Immutable
st_disjoint(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a does not overlap, touch or is within geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_distance(geography_a: geography, geography_b: geography) → float

Returns the distance in meters between geography_a and geography_b. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geography_a: geography, geography_b: geography, use_spheroid: bool) → float

Returns the distance in meters between geography_a and geography_b.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance between the given geometries.

+		Immutable
st_distance(geometry_a_str: string, geometry_b_str: string) → float

Returns the distance between the given geometries.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_distancesphere(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_distancespheroid(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a spheroid.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_endpoint(geometry: geometry) → geometry

Returns the last point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_envelope(box2d: box2d) → geometry

Returns a bounding geometry for the given box.

+		Immutable
st_envelope(geometry: geometry) → geometry

Returns a bounding envelope for the given geometry.

+

For geometries which have a POINT or LINESTRING bounding box (i.e. is a single point +or a horizontal or vertical line), a POINT or LINESTRING is returned. Otherwise, the +returned POLYGON will be ordered Bottom Left, Top Left, Top Right, Bottom Right, +Bottom Left.

+		Immutable
st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string, parent_only: bool) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+

The parent_only boolean is always ignored.

+		Stable
st_estimatedextent(table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_expand(box2d: box2d, delta: float) → box2d

Extends the box2d by delta units across all dimensions.

+		Immutable
st_expand(box2d: box2d, delta_x: float, delta_y: float) → box2d

Extends the box2d by delta_x units in the x dimension and delta_y units in the y dimension.

+		Immutable
st_expand(geometry: geometry, delta: float) → geometry

Extends the bounding box represented by the geometry by delta units across all dimensions, returning a Polygon representing the new bounding box.

+		Immutable
st_expand(geometry: geometry, delta_x: float, delta_y: float) → geometry

Extends the bounding box represented by the geometry by delta_x units in the x dimension and delta_y units in the y dimension, returning a Polygon representing the new bounding box.

+		Immutable
st_exteriorring(geometry: geometry) → geometry

Returns the exterior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon.

+		Immutable
st_flipcoordinates(geometry: geometry) → geometry

Returns a new geometry with the X and Y axes flipped.

+		Immutable
st_force2d(geometry: geometry) → geometry

Returns a Geometry that is forced into XY layout with any Z or M dimensions discarded.

+		Immutable
st_force3d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to 0. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry, defaultM: float) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to the specified default M value. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force4d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZM layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float, defaultM: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified Z value. If a M coordinate doesn’t exist, it will be set to the specified M value.

+		Immutable
st_forcecollection(geometry: geometry) → geometry

Converts the geometry into a GeometryCollection.

+		Immutable
st_forcepolygonccw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_forcepolygoncw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Frechet distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Frechet distance between the given geometries, with the given segment densification (range 0.0-1.0, -1 to disable).

+

Smaller densify_frac gives a more accurate Fréchet distance. However, the computation time and memory usage increases with the square of the number of subsegments.

+

This function utilizes the GEOS module.

+		Immutable
st_generatepoints(geometry: geometry, npoints: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. Uses system time as a seed. +The requested number of points must be not larger than 65336.

+		Volatile
st_generatepoints(geometry: geometry, npoints: int4, seed: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. +The requested number of points must be not larger than 65336.

+		Immutable
st_geogfromewkb(val: bytes) → geography

Returns the Geography from an EWKB representation.

+		Immutable
st_geogfromewkt(val: string) → geography

Returns the Geography from an EWKT representation.

+		Immutable
st_geogfromgeojson(val: string) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromgeojson(val: jsonb) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geogfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geogfromwkb(bytes: bytes, srid: int) → geography

Returns the Geography from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geogfromwkb(val: bytes) → geography

Returns the Geography from a WKB (or EWKB) representation.

+		Immutable
st_geographyfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geographyfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geohash(geography: geography) → string

Returns a GeoHash representation of the geeographywith full precision if a point is provided, or with variable precision based on the size of the feature.

+		Immutable
st_geohash(geography: geography, precision: int) → string

Returns a GeoHash representation of the geography with the supplied precision.

+		Immutable
st_geohash(geometry: geometry) → string

Returns a GeoHash representation of the geometry with full precision if a point is provided, or with variable precision based on the size of the feature. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geohash(geometry: geometry, precision: int) → string

Returns a GeoHash representation of the geometry with the supplied precision. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geomcollfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomcollfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geometryfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geometryfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geometryn(geometry: geometry, n: int) → geometry

Returns the n-th Geometry (1-indexed). Returns NULL if out of bounds.

+		Immutable
st_geometrytype(geometry: geometry) → string

Returns the type of geometry as a string prefixed with ST_.

+

This function utilizes the GEOS module.

+		Immutable
st_geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
st_geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
st_geomfromgeohash(geohash: string) → geometry

Return a POLYGON Geometry from a GeoHash string with max precision.

+		Immutable
st_geomfromgeohash(geohash: string, precision: int) → geometry

Return a POLYGON Geometry from a GeoHash string with supplied precision.

+		Immutable
st_geomfromgeojson(val: string) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromgeojson(val: jsonb) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geomfromwkb(bytes: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geomfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_hasarc(geometry: geometry) → bool

Returns whether there is a CIRCULARSTRING in the geometry.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Hausdorff distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Hausdorff distance between the given geometries, with the given segment densification (range 0.0-1.0).

+

This function utilizes the GEOS module.

+		Immutable
st_interiorringn(geometry: geometry, n: int) → geometry

Returns the n-th (1-indexed) interior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon, or the ring does not exist.

+		Immutable
st_intersection(geography_a: geography, geography_b: geography) → geography

Returns the point intersections of the given geographies.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a_str: string, geometry_b_str: string) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_isclosed(geometry: geometry) → bool

Returns whether the geometry is closed as defined by whether the start and end points are coincident. Points are considered closed, empty geometries are not. For collections and multi-types, all members must be closed, as must all polygon rings.

+		Immutable
st_iscollection(geometry: geometry) → bool

Returns whether the geometry is of a collection type (including multi-types).

+		Immutable
st_isempty(geometry: geometry) → bool

Returns whether the geometry is empty.

+		Immutable
st_ispolygonccw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are considered counter-clockwise.

+		Immutable
st_ispolygoncw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are considered clockwise.

+		Immutable
st_isring(geometry: geometry) → bool

Returns whether the geometry is a single linestring that is closed and simple, as defined by ST_IsClosed and ST_IsSimple.

+

This function utilizes the GEOS module.

+		Immutable
st_issimple(geometry: geometry) → bool

Returns true if the geometry has no anomalous geometric points, e.g. that it intersects with or lies tangent to itself.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry) → bool

Returns whether the geometry is valid as defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry, flags: int) → bool

Returns whether the geometry is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry) → string

Returns a string containing the reason the geometry is invalid along with the point of interest, or “Valid Geometry” if it is valid. Validity is defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry, flags: int) → string

Returns the reason the geometry is invalid or “Valid Geometry” if it is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidtrajectory(geometry: geometry) → bool

Returns whether the geometry encodes a valid trajectory.

+

Note the geometry must be a LineString with M coordinates.

+		Immutable
st_length(geography: geography) → float

Returns the length of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geography: geography, use_spheroid: bool) → float

Returns the length of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_length(geometry_str: string) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_length2d(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_linecrossingdirection(linestring_a: geometry, linestring_b: geometry) → int

Returns an interger value defining behavior of crossing of lines: +0: lines do not cross, +-1: linestring_b crosses linestring_a from right to left, +1: linestring_b crosses linestring_a from left to right, +-2: linestring_b crosses linestring_a multiple times from right to left, +2: linestring_b crosses linestring_a multiple times from left to right, +-3: linestring_b crosses linestring_a multiple times from left to left, +3: linestring_b crosses linestring_a multiple times from right to right.

+

Note that the top vertex of the segment touching another line does not count as a crossing, but the bottom vertex of segment touching another line is considered a crossing.

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string) → geometry

Creates a LineString from an Encoded Polyline string.

+

Returns valid results only if the polyline was encoded with 5 decimal places.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string, precision: int4) → geometry

Creates a LineString from an Encoded Polyline string.

+

Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefrommultipoint(geometry: geometry) → geometry

Creates a LineString from a MultiPoint geometry.

+		Immutable
st_linefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_lineinterpolatepoint(geometry: geometry, fraction: float) → geometry

Returns a point along the given LineString which is at given fraction of LineString’s total length.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float, repeat: bool) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length. If repeat is false (default true) then it returns first point.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_linelocatepoint(line: geometry, point: geometry) → float

Returns a float between 0 and 1 representing the location of the closest point on LineString to the given Point, as a fraction of total 2d line length.

+		Immutable
st_linemerge(geometry: geometry) → geometry

Returns a LineString or MultiLineString by joining together constituents of a MultiLineString with matching endpoints. If the input is not a MultiLineString or LineString, an empty GeometryCollection is returned.

+

This function utilizes the GEOS module.

+		Immutable
st_linestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: decimal, end_fraction: decimal) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: float, end_fraction: float) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_longestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the max distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the maximum distance between the geometry’s vertexes. The function will return the longest line that was discovered first when comparing maximum distances if more than one is found.

+		Immutable
st_m(geometry: geometry) → float

Returns the M coordinate of a geometry if it is a Point.

+		Immutable
st_makebox2d(geometry_a: geometry, geometry_b: geometry) → box2d

Creates a box2d from two points. Errors if arguments are not two non-empty points.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with SRID 0.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float, srid: int) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with the given SRID.

+		Immutable
st_makepoint(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float) → geometry

Returns a new Point with the given X, Y, and Z coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float, m: float) → geometry

Returns a new Point with the given X, Y, Z, and M coordinates.

+		Immutable
st_makepointm(x: float, y: float, m: float) → geometry

Returns a new Point with the given X, Y, and M coordinates.

+		Immutable
st_makepolygon(geometry: geometry) → geometry

Returns a new Polygon with the given outer LineString.

+		Immutable
st_makepolygon(outer: geometry, interior: anyelement[]) → geometry

Returns a new Polygon with the given outer LineString and interior (hole) LineString(s).

+		Immutable
st_makevalid(geometry: geometry) → geometry

Returns a valid form of the given geometry according to the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_maxdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the maximum distance across every pair of points comprising the given geometries. Note if the geometries are the same, it will return the maximum distance between the geometry’s vertexes.

+		Immutable
st_memsize(geometry: geometry) → int

Returns the amount of memory space (in bytes) the geometry takes.

+		Immutable
st_minimumboundingcircle(geometry: geometry) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingcircle(geometry: geometry, num_segs: int) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingradius(geometry: geometry) → tuple{geometry AS center, float AS radius}

Returns a record containing the center point and radius of the smallest circle that can fully contains the given geometry.

+		Immutable
st_minimumclearance(geometry: geometry) → float

Returns the minimum distance a vertex can move before producing an invalid geometry. Returns Infinity if no minimum clearance can be found (e.g. for a single point).

+		Immutable
st_minimumclearanceline(geometry: geometry) → geometry

Returns a LINESTRING spanning the minimum distance a vertex can move before producing an invalid geometry. If no minimum clearance can be found (e.g. for a single point), an empty LINESTRING is returned.

+		Immutable
st_mlinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mlinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mpointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multi(geometry: geometry) → geometry

Returns the geometry as a new multi-geometry, e.g converts a POINT to a MULTIPOINT. If the input is already a multitype or collection, it is returned as is.

+		Immutable
st_multilinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multipointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_ndims(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_node(geometry: geometry) → geometry

Adds a node on a geometry for each intersection. Resulting geometry is always a MultiLineString.

+		Immutable
st_normalize(geometry: geometry) → geometry

Returns the geometry in its normalized form.

+

This function utilizes the GEOS module.

+		Immutable
st_npoints(geometry: geometry) → int

Returns the number of points in a given Geometry. Works for any shape type.

+		Immutable
st_nrings(geometry: geometry) → int

Returns the number of rings in a Polygon Geometry. Returns 0 if the shape is not a Polygon.

+		Immutable
st_numgeometries(geometry: geometry) → int

Returns the number of shapes inside a given Geometry.

+		Immutable
st_numinteriorring(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numinteriorrings(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numpoints(geometry: geometry) → int

Returns the number of points in a LineString. Returns NULL if the Geometry is not a LineString.

+		Immutable
st_orderingequals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is exactly equal to geometry_b, having all coordinates in the same order, as well as the same type, SRID, bounding box, and so on.

+		Immutable
st_orientedenvelope(geometry: geometry) → geometry

Returns a minimum rotated rectangle enclosing a geometry. +Note that more than one minimum rotated rectangle may exist. +May return a Point or LineString in the case of degenerate inputs.

+		Immutable
st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_perimeter(geography: geography) → float

Returns the perimeter of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geography: geography, use_spheroid: bool) → float

Returns the perimeter of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_perimeter2d(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_point(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_pointfromgeohash(geohash: string) → geometry

Return a POINT Geometry from a GeoHash string with max precision.

+		Immutable
st_pointfromgeohash(geohash: string, precision: int) → geometry

Return a POINT Geometry from a GeoHash string with supplied precision.

+		Immutable
st_pointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Point, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_pointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointinsidecircle(geometry: geometry, x_coord: float, y_coord: float, radius: float) → bool

Returns the true if the geometry is a point and is inside the circle. Returns false otherwise.

+		Immutable
st_pointn(geometry: geometry, n: int) → geometry

Returns the n-th Point of a LineString (1-indexed). Returns NULL if out of bounds or not a LineString.

+		Immutable
st_pointonsurface(geometry: geometry) → geometry

Returns a point that intersects with the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_points(geometry: geometry) → geometry

Returns all coordinates in the given Geometry as a MultiPoint, including duplicates.

+		Immutable
st_polyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygon(geometry: geometry, srid: int) → geometry

Returns a new Polygon from the given LineString and sets its SRID. It is equivalent to ST_MakePolygon with a single argument followed by ST_SetSRID.

+		Immutable
st_polygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_project(geography: geography, distance: float, azimuth: float) → geography

Returns a point projected from a start point along a geodesic using a given distance and azimuth (bearing). +This is known as the direct geodesic problem.

+

The distance is given in meters. Negative values are supported.

+

The azimuth (also known as heading or bearing) is given in radians. It is measured clockwise from true north (azimuth zero). +East is azimuth π/2 (90 degrees); south is azimuth π (180 degrees); west is azimuth 3π/2 (270 degrees). +Negative azimuth values and values greater than 2π (360 degrees) are supported.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, bnr: int) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b using the given boundary node rule (1:OGC/MOD2, 2:Endpoint, 3:MultivalentEndpoint, 4:MonovalentEndpoint).

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, pattern: string) → bool

Returns whether the DE-9IM spatial relation between geometry_a and geometry_b matches the DE-9IM pattern.

+

This function utilizes the GEOS module.

+		Immutable
st_relatematch(intersection_matrix: string, pattern: string) → bool

Returns whether the given DE-9IM intersection matrix satisfies the given pattern.

+		Immutable
st_removepoint(line_string: geometry, index: int) → geometry

Removes the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_removerepeatedpoints(geometry: geometry) → geometry

Returns a geometry with repeated points removed.

+		Immutable
st_removerepeatedpoints(geometry: geometry, tolerance: float) → geometry

Returns a geometry with repeated points removed, within the given distance tolerance.

+		Immutable
st_reverse(geometry: geometry) → geometry

Returns a modified geometry by reversing the order of its vertices.

+		Immutable
st_rotate(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_point: geometry) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_x: float, origin_y: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotatex(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the x axis by a rotation angle.

+		Immutable
st_rotatey(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the y axis by a rotation angle.

+		Immutable
st_rotatez(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the z axis by a rotation angle.

+		Immutable
st_s2covering(geography: geography) → geography

Returns a geography which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geography: geography, settings: string) → geography

Returns a geography which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geography, 's2_max_level=15,s2_level_mod=3').

+		Immutable
st_s2covering(geometry: geometry) → geometry

Returns a geometry which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geometry: geometry, settings: string) → geometry

Returns a geometry which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geometry, 's2_max_level=15,s2_level_mod=3')

+		Immutable
st_scale(g: geometry, factor: geometry) → geometry

Returns a modified Geometry scaled by taking in a Geometry as the factor.

+		Immutable
st_scale(g: geometry, factor: geometry, origin: geometry) → geometry

Returns a modified Geometry scaled by the Geometry factor relative to a false origin.

+		Immutable
st_scale(geometry: geometry, x_factor: float, y_factor: float) → geometry

Returns a modified Geometry scaled by the given factors.

+		Immutable
st_segmentize(geography: geography, max_segment_length_meters: float) → geography

Returns a modified Geography having no segment longer than the given max_segment_length meters.

+

The calculations are done on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_segmentize(geometry: geometry, max_segment_length: float) → geometry

Returns a modified Geometry having no segment longer than the given max_segment_length. Length units are in units of spatial reference.

+		Immutable
st_setpoint(line_string: geometry, index: int, point: geometry) → geometry

Sets the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_setsrid(geography: geography, srid: int) → geography

Sets a Geography to a new SRID without transforming the coordinates.

+		Immutable
st_setsrid(geometry: geometry, srid: int) → geometry

Sets a Geometry to a new SRID without transforming the coordinates.

+		Immutable
st_sharedpaths(geometry_a: geometry, geometry_b: geometry) → geometry

Returns a collection containing paths shared by the two input geometries.

+

Those going in the same direction are in the first element of the collection, +those going in the opposite direction are in the second element. +The paths themselves are given in the direction of the first geometry.

+		Immutable
st_shiftlongitude(geometry: geometry) → geometry

Returns a modified version of a geometry in which the longitude (X coordinate) of each point is incremented by 360 if it is <0 and decremented by 360 if it is >180. The result is only meaningful if the coordinates are in longitude/latitude.

+		Immutable
st_shortestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the minimum distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the minimum distance between the geometry’s vertexes. The function will return the shortest line that was discovered first when comparing minimum distances if more than one is found.

+		Immutable
st_simplify(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm.

+

This function utilizes the GEOS module.

+		Immutable
st_simplify(geometry: geometry, tolerance: float, preserve_collapsed: bool) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, retaining objects that would be too small given the tolerance if preserve_collapsed is set to true.

+		Immutable
st_simplifypreservetopology(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, avoiding the creation of invalid geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_snap(input: geometry, target: geometry, tolerance: float) → geometry

Snaps the vertices and segments of input geometry the target geometry’s vertices. +Tolerance is used to control where snapping is performed. The result geometry is the input geometry with the vertices snapped. +If no snapping occurs then the input geometry is returned unchanged.

+		Immutable
st_snaptogrid(geometry: geometry, origin: geometry, size_x: float, size_y: float, size_z: float, size_m: float) → geometry

Snap a geometry to a grid defined by the given origin and X, Y, Z, and M cell sizes. Any dimension with a 0 cell size will not be snapped.

+		Immutable
st_snaptogrid(geometry: geometry, origin_x: float, origin_y: float, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y based on an origin of (origin_x, origin_y).

+		Immutable
st_snaptogrid(geometry: geometry, size: float) → geometry

Snap a geometry to a grid of the given size. The specified size is only used to snap X and Y coordinates.

+		Immutable
st_snaptogrid(geometry: geometry, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y.

+		Immutable
st_srid(geography: geography) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geography as defined in spatial_ref_sys table.

+		Immutable
st_srid(geometry: geometry) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geometry as defined in spatial_ref_sys table.

+		Immutable
st_startpoint(geometry: geometry) → geometry

Returns the first point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_subdivide(geometry: geometry) → geometry

Returns a geometry divided into parts, where each part contains no more than 256 vertices.

+		Immutable
st_subdivide(geometry: geometry, max_vertices: int4) → geometry

Returns a geometry divided into parts, where each part contains no more than the number of vertices provided.

+		Immutable
st_summary(geography: geography) → string

Returns a text summary of the contents of the geography.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_summary(geometry: geometry) → string

Returns a text summary of the contents of the geometry.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_swapordinates(geometry: geometry, swap_ordinate_string: string) → geometry

Returns a version of the given geometry with given ordinates swapped. +The swap_ordinate_string parameter is a 2-character string naming the ordinates to swap. Valid names are: x, y, z and m.

+		Immutable
st_symdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_symmetricdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4, bounds: geometry) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4, bounds: geometry, margin: float) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, srid: int) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates. The supplied SRID is set on the new geometry.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, srid: int) → geometry

Transforms a geometry into the given SRID coordinate reference system by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system referenced by the projection text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float, delta_z: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_transscale(geometry: geometry, delta_x: float, delta_y: float, x_factor: float, y_factor: float) → geometry

Translates the geometry using the deltaX and deltaY args, then scales it using the XFactor, YFactor args, working in 2D only.

+		Immutable
st_unaryunion(geometry: geometry) → geometry

Returns a union of the components for any geometry or geometry collection provided. Dissolves boundaries of a multipolygon.

+		Immutable
st_voronoilines(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoipolygons(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_wkbtosql(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_wkttosql(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_x(geometry: geometry) → float

Returns the X coordinate of a geometry if it is a Point.

+		Immutable
st_xmax(box2d: box2d) → float

Returns the maximum X ordinate of a box2d.

+		Immutable
st_xmax(geometry: geometry) → float

Returns the maximum X ordinate of a geometry.

+		Immutable
st_xmin(box2d: box2d) → float

Returns the minimum X ordinate of a box2d.

+		Immutable
st_xmin(geometry: geometry) → float

Returns the minimum X ordinate of a geometry.

+		Immutable
st_y(geometry: geometry) → float

Returns the Y coordinate of a geometry if it is a Point.

+		Immutable
st_ymax(box2d: box2d) → float

Returns the maximum Y ordinate of a box2d.

+		Immutable
st_ymax(geometry: geometry) → float

Returns the maximum Y ordinate of a geometry.

+		Immutable
st_ymin(box2d: box2d) → float

Returns the minimum Y ordinate of a box2d.

+		Immutable
st_ymin(geometry: geometry) → float

Returns the minimum Y ordinate of a geometry.

+		Immutable
st_z(geometry: geometry) → float

Returns the Z coordinate of a geometry if it is a Point.

+		Immutable
st_zmflag(geometry: geometry) → int2

Returns a code based on the ZM coordinate dimension of a geometry (XY = 0, XYM = 1, XYZ = 2, XYZM = 3).

+		Immutable
+ +### String and byte functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ascii(val: string) → int

Returns the character code of the first character in val. Despite the name, the function supports Unicode too.

+		Immutable
bit_count(val: bytes) → int

Calculates the number of bits set used to represent val.

+		Immutable
bit_count(val: varbit) → int

Calculates the number of bits set used to represent val.

+		Immutable
bit_length(val: bytes) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: string) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
bitmask_and(a: string, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: string, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
btrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning or end of input (applies recursively).

+

For example, btrim('doggie', 'eod') returns ggi.

+		Immutable
btrim(val: string) → string

Removes all spaces from the beginning and end of val.

+		Immutable
char_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
char_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
character_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
character_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
chr(val: int) → string

Returns the character with the code given in val. Inverse function of ascii().

+		Immutable
compress(data: bytes, codec: string) → bytes

Compress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
concat(any...) → string

Concatenates a comma-separated list of strings.

+		Immutable
concat_ws(string, any...) → string

Uses the first argument as a separator between the concatenation of the subsequent arguments.

+

For example concat_ws('!','wow','great') returns wow!great.

+		Immutable
convert_from(str: bytes, enc: string) → string

Decode the bytes in str into a string using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
convert_to(str: string, enc: string) → bytes

Encode the string str as a byte array using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
decode(text: string, format: string) → bytes

Decodes data using format (hex / escape / base64).

+		Immutable
decompress(data: bytes, codec: string) → bytes

Decompress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
difference(source: string, target: string) → int

Convert two strings to their Soundex codes and report the number of matching code positions.

+		Immutable
encode(data: bytes, format: string) → string

Encodes data using format (hex / escape / base64).

+		Immutable
format(string, any...) → string

Interprets the first argument as a format string similar to C sprintf and interpolates the remaining arguments.

+		Stable
from_ip(val: bytes) → string

Converts the byte string representation of an IP to its character string representation.

+		Immutable
from_uuid(val: bytes) → string

Converts the byte string representation of a UUID to its character string representation.

+		Immutable
get_bit(bit_string: varbit, index: int) → int

Extracts a bit at given index in the bit array.

+		Immutable
get_bit(byte_string: bytes, index: int) → int

Extracts a bit at the given index in the byte array.

+		Immutable
get_byte(byte_string: bytes, index: int) → int

Extracts a byte at the given index in the byte array.

+		Immutable
initcap(val: string) → string

Capitalizes the first letter of val.

+		Immutable
left(input: bytes, return_set: int) → bytes

Returns the first return_set bytes from input.

+		Immutable
left(input: string, return_set: int) → string

Returns the first return_set characters from input.

+		Immutable
length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
length(val: string) → int

Calculates the number of characters in val.

+		Immutable
length(val: varbit) → int

Calculates the number of bits in val.

+		Immutable
lower(val: string) → string

Converts all characters in val to their lower-case equivalents.

+		Immutable
lpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the left of string.If string is longer than length it is truncated.

+		Immutable
lpad(string: string, length: int, fill: string) → string

Pads string by adding fill to the left of string to make it length. If string is longer than length it is truncated.

+		Immutable
ltrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning (left-hand side) of input (applies recursively).

+

For example, ltrim('doggie', 'od') returns ggie.

+		Immutable
ltrim(val: string) → string

Removes all spaces from the beginning (left-hand side) of val.

+		Immutable
md5(bytes...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
md5(string...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
octet_length(val: bytes) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: string) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int) → string

Replaces characters in input with overlay_val starting at start_pos (begins at 1).

+

For example, overlay('doggie', 'CAT', 2) returns dCATie.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int, end_pos: int) → string

Deletes the characters in input between start_pos and end_pos (count starts at 1), and then insert overlay_val at start_pos.

+		Immutable
parse_date(string: string, datestyle: string) → date

Parses a date assuming it is in format specified by DateStyle.

+		Immutable
parse_date(val: string) → date

Parses a date assuming it is in MDY format.

+		Immutable
parse_ident(qualified_identifier: string) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. Extra characters after the last identifier are considered an error

+		Immutable
parse_ident(qualified_identifier: string, strict: bool) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. If strict is false, then extra characters after the last identifier are ignored.

+		Immutable
parse_interval(string: string, style: string) → interval

Convert a string to an interval using the given IntervalStyle.

+		Immutable
parse_interval(val: string) → interval

Convert a string to an interval assuming the Postgres IntervalStyle.

+		Immutable
parse_time(string: string, timestyle: string) → time

Parses a time assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_time(val: string) → time

Parses a time assuming the date (if any) is in MDY format.

+		Immutable
parse_timestamp(string: string, datestyle: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates formatted using the given DateStyle.

+		Immutable
parse_timestamp(val: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates are in MDY format.

+		Immutable
parse_timetz(string: string, timestyle: string) → timetz

Parses a timetz assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_timetz(val: string) → timetz

Parses a timetz assuming the date (if any) is in MDY format.

+		Immutable
prettify_statement(statement: string, line_width: int, align_mode: int, case_mode: int) → string

Prettifies a statement using a user-configured pretty-printing config. +Align mode values range from 0 - 3, representing no, partial, full, and extra alignment respectively. +Case mode values range between 0 - 1, representing lower casing and upper casing respectively.

+		Immutable
prettify_statement(val: string) → string

Prettifies a statement using a the default pretty-printing config.

+		Immutable
quote_ident(val: string) → string

Return val suitably quoted to serve as identifier in a SQL statement.

+		Immutable
quote_literal(val: string) → string

Return val suitably quoted to serve as string literal in a SQL statement.

+		Immutable
quote_literal(val: anyelement) → string

Coerce val to a string and then quote it as a literal.

+		Stable
quote_nullable(val: string) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Immutable
quote_nullable(val: anyelement) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Stable
regexp_extract(input: string, regex: string) → string

Returns the first match for the Regular Expression regex in input.

+		Immutable
regexp_replace(input: string, regex: string, replace: string) → string

Replaces matches for the Regular Expression regex in input with the Regular Expression replace.

+		Immutable
regexp_replace(input: string, regex: string, replace: string, flags: string) → string

Replaces matches for the regular expression regex in input with the regular expression replace using flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
repeat(input: string, repeat_counter: int) → string

Concatenates input repeat_counter number of times.

+

For example, repeat('dog', 2) returns dogdog.

+		Immutable
replace(input: string, find: string, replace: string) → string

Replaces all occurrences of find with replace in input

+		Immutable
reverse(val: string) → string

Reverses the order of the string’s characters.

+		Immutable
right(input: bytes, return_set: int) → bytes

Returns the last return_set bytes from input.

+		Immutable
right(input: string, return_set: int) → string

Returns the last return_set characters from input.

+		Immutable
rpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the right of string. If string is longer than length it is truncated.

+		Immutable
rpad(string: string, length: int, fill: string) → string

Pads string to length by adding fill to the right of string. If string is longer than length it is truncated.

+		Immutable
rtrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the end (right-hand side) of input (applies recursively).

+

For example, rtrim('doggie', 'ei') returns dogg.

+		Immutable
rtrim(val: string) → string

Removes all spaces from the end (right-hand side) of val.

+		Immutable
set_bit(bit_string: varbit, index: int, to_set: int) → varbit

Updates a bit at given index in the bit array.

+		Immutable
set_bit(byte_string: bytes, index: int, to_set: int) → bytes

Updates a bit at the given index in the byte array.

+		Immutable
set_byte(byte_string: bytes, index: int, to_set: int) → bytes

Updates a byte at the given index in the byte array.

+		Immutable
sha1(bytes...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha1(string...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha224(bytes...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha224(string...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha256(bytes...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha256(string...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha384(bytes...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha384(string...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha512(bytes...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
sha512(string...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
similar_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_to_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
split_part(input: string, delimiter: string, return_index_pos: int) → string

Splits input using delimiter and returns the field at return_index_pos (starting from 1). If return_index_pos is negative, it returns the |return_index_pos|'th field from the end.

+

For example, split_part('123.456.789.0', '.', 3) returns 789.

+		Immutable
strpos(input: bytes, find: bytes) → int

Calculates the position where the byte subarray find begins in input.

+		Immutable
strpos(input: string, find: string) → int

Calculates the position where the string find begins in input.

+

For example, strpos('doggie', 'gie') returns 4.

+		Immutable
strpos(input: varbit, find: varbit) → int

Calculates the position where the bit subarray find begins in input.

+		Immutable
substr(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substr(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substr(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substring(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substring(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring_index(input: string, delim: string, count: int) → string

Returns a substring of input before count occurrences of delim. +If count is positive, the leftmost part is returned. If count is negative, the rightmost part is returned.

+		Immutable
to_char_with_style(date: date, datestyle: string) → string

Convert an date to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_char_with_style(interval: interval, style: string) → string

Convert an interval to a string using the given IntervalStyle.

+		Immutable
to_char_with_style(timestamp: timestamp, datestyle: string) → string

Convert an timestamp to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_english(val: int) → string

This function enunciates the value of its argument using English cardinals.

+		Immutable
to_hex(val: bytes) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: int) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: string) → string

Converts val to its hexadecimal representation.

+		Immutable
to_ip(val: string) → bytes

Converts the character string representation of an IP to its byte string representation.

+		Immutable
to_uuid(val: string) → bytes

Converts the character string representation of a UUID to its byte string representation.

+		Immutable
translate(input: string, find: string, replace: string) → string

In input, replaces the first character from find with the first character in replace; repeat for each character in find.

+

For example, translate('doggie', 'dog', '123'); returns 1233ie.

+		Immutable
ulid_to_uuid(val: string) → uuid

Converts a ULID string to its UUID-encoded representation.

+		Immutable
unaccent(val: string) → string

Removes accents (diacritic signs) from the text provided in val.

+		Immutable
upper(val: string) → string

Converts all characters in val to their to their upper-case equivalents.

+		Immutable
+ +### System info functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cluster_logical_timestamp() → decimal

Returns the logical time of the current transaction as +a CockroachDB HLC in decimal form.

+

Note that uses of this function disable server-side optimizations and +may increase either contention or retry errors, or both.

+

Returns an error if run in a transaction with an isolation level weaker than SERIALIZABLE.

+		Volatile
current_database() → string

Returns the current database.

+		Stable
current_schema() → string

Returns the current schema.

+		Stable
current_schemas(include_pg_catalog: bool) → string[]

Returns the valid schemas in the search path.

+		Stable
current_user() → string

Returns the current user. This function is provided for compatibility with PostgreSQL.

+		Stable
session_user() → string

Returns the session user. This function is provided for compatibility with PostgreSQL.

+		Stable
to_regclass(text: string) → regtype

Translates a textual relation name to its OID

+		Stable
to_regnamespace(text: string) → regtype

Translates a textual schema name to its OID

+		Stable
to_regproc(text: string) → regtype

Translates a textual function or procedure name to its OID

+		Stable
to_regprocedure(text: string) → regtype

Translates a textual function or procedure name(with argument types) to its OID

+		Stable
to_regrole(text: string) → regtype

Translates a textual role name to its OID

+		Stable
to_regtype(text: string) → regtype

Translates a textual type name to its OID

+		Stable
version() → string

Returns the node’s version of CockroachDB.

+		Volatile
+ +### TIMETZ functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
current_time() → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time() → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_time(precision: int) → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time(precision: int) → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → timetz

Returns the current transaction’s time with time zone.

+		Stable
localtime(precision: int) → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime(precision: int) → timetz

Returns the current transaction’s time with time zone.

+		Stable
+ +### Trigrams functions + + + + + + +
Function → ReturnsDescriptionVolatility
show_trgm(input: string) → string[]

Returns an array of all the trigrams in the given string.

+		Immutable
similarity(left: string, right: string) → float

Returns a number that indicates how similar the two arguments are. The range of the result is zero (indicating that the two strings are completely dissimilar) to one (indicating that the two strings are identical).

+		Immutable
+ +### UUID functions + + + + + +
Function → ReturnsDescriptionVolatility
uuid_to_ulid(val: uuid) → string

Converts a UUID-encoded ULID to its string representation.

+		Immutable
+ +### Compatibility functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
col_description(table_oid: oid, column_number: int) → string

Returns the comment for a table column, which is specified by the OID of its table and its column number. (obj_description cannot be used for table columns, since columns do not have OIDs of their own.)

+		Stable
current_setting(setting_name: string) → string

System info

+		Stable
current_setting(setting_name: string, missing_ok: bool) → string

System info

+		Stable
format_type(type_oid: oid, typemod: int) → string

Returns the SQL name of a data type that is identified by its type OID and possibly a type modifier. Currently, the type modifier is ignored.

+		Stable
getdatabaseencoding() → string

Returns the current encoding name used by the database.

+		Stable
has_any_column_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_column_privilege(table: string, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: string, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_database_privilege(database: string, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(database: oid, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(user: string, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: string, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_foreign_data_wrapper_privilege(fdw: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(fdw: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_function_privilege(function: string, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(function: oid, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(user: string, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: string, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_language_privilege(language: string, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(language: oid, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(user: string, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: string, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_schema_privilege(schema: string, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(schema: oid, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_sequence_privilege(sequence: string, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(sequence: oid, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_server_privilege(server: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(server: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_system_privilege(privilege: string) → bool

Returns whether or not the current user has privileges for system.

+		Stable
has_system_privilege(user: string, privilege: string) → bool

Returns whether or not the user has privileges for system.

+		Stable
has_system_privilege(user: oid, privilege: string) → bool

Returns whether or not the user has privileges for system.

+		Stable
has_table_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_tablespace_privilege(tablespace: string, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(tablespace: oid, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_type_privilege(type: string, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(type: oid, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(user: string, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: string, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
information_schema._pg_numeric_precision(typid: oid, typmod: int4) → int

Returns the precision of the given type with type modifier

+		Immutable
information_schema._pg_numeric_precision_radix(typid: oid, typmod: int4) → int

Returns the radix of the given type with type modifier

+		Immutable
information_schema._pg_numeric_scale(typid: oid, typmod: int4) → int

Returns the scale of the given type with type modifier

+		Immutable
nameconcatoid(name: string, oid: oid) → name

Used in the information_schema to produce specific_name columns, which are supposed to be unique per schema. The result is the same as ($1::text || ‘_’ || $2::text)::name except that, if it would not fit in 63 characters, we make it do so by truncating the name input (not the oid).

+		Immutable
obj_description(object_oid: oid) → string

Returns the comment for a database object specified by its OID alone. This is deprecated since there is no guarantee that OIDs are unique across different system catalogs; therefore, the wrong comment might be returned.

+		Stable
obj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a database object specified by its OID and the name of the containing system catalog. For example, obj_description(123456, ‘pg_class’) would retrieve the comment for the table with OID 123456.

+		Stable
oidvectortypes(vector: oidvector) → string

Generates a comma seperated string of type names from an oidvector.

+		Stable
pg_backend_pid() → int

Returns a numerical ID attached to this session. This ID is part of the query cancellation key used by the wire protocol. This function was only added for compatibility, and unlike in Postgres, the returned value does not correspond to a real process ID.

+		Stable
pg_collation_for(str: anyelement) → string

Returns the collation of the argument

+		Stable
pg_column_is_updatable(reloid: oid, attnum: int2, include_triggers: bool) → bool

Returns whether the given column can be updated.

+		Stable
pg_column_size(any...) → int

Return size in bytes of the column provided as an argument

+		Stable
pg_function_is_visible(oid: oid) → bool

Returns whether the function with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_get_function_arg_default(func_oid: oid, arg_num: int4) → string

Get textual representation of a function argument’s default value. The second argument of this function is the argument number among all arguments (i.e. proallargtypes, not proargtypes), starting with 1, because that’s how information_schema.sql uses it.

+		Stable
pg_get_function_arguments(func_oid: oid) → string

Returns the argument list (with defaults) necessary to identify a function, in the form it would need to appear in within CREATE FUNCTION.

+		Stable
pg_get_function_identity_arguments(func_oid: oid) → string

Returns the argument list (without defaults) necessary to identify a function, in the form it would need to appear in within ALTER FUNCTION, for instance.

+		Stable
pg_get_function_result(func_oid: oid) → string

Returns the types of the result of the specified function.

+		Stable
pg_get_functiondef(func_oid: oid) → string

For user-defined functions, returns the definition of the specified function. For builtin functions, returns the name of the function.

+		Stable
pg_get_indexdef(index_oid: oid) → string

Gets the CREATE INDEX command for index

+		Stable
pg_get_indexdef(index_oid: oid, column_no: int, pretty_bool: bool) → string

Gets the CREATE INDEX command for index, or definition of just one index column when given a non-zero column number

+		Stable
pg_get_serial_sequence(table_name: string, column_name: string) → string

Returns the name of the sequence used by the given column_name in the table table_name.

+		Stable
pg_get_viewdef(view_oid: oid) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_get_viewdef(view_oid: oid, pretty_bool: bool) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_has_role(role: string, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(role: oid, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(user: string, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: string, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_is_other_temp_schema(oid: oid) → bool

Returns true if the given OID is the OID of another session’s temporary schema. (This can be useful, for example, to exclude other sessions’ temporary tables from a catalog display.)

+		Stable
pg_my_temp_schema() → oid

Returns the OID of the current session’s temporary schema, or zero if it has none (because it has not created any temporary tables).

+		Stable
pg_relation_is_updatable(reloid: oid, include_triggers: bool) → int4

Returns the update events the relation supports.

+		Stable
pg_sequence_last_value(sequence_oid: oid) → int

Returns the last value generated by a sequence, or NULL if the sequence has not been used yet.

+		Volatile
pg_sleep(seconds: float) → bool

pg_sleep makes the current session’s process sleep until seconds seconds have elapsed. seconds is a value of type double precision, so fractional-second delays can be specified.

+		Volatile
pg_table_is_visible(oid: oid) → bool

Returns whether the table with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_type_is_visible(oid: oid) → bool

Returns whether the type with the given OID belongs to one of the schemas on the search path.

+		Stable
set_config(setting_name: string, new_value: string, is_local: bool) → string

System info

+		Volatile
shobj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a shared database object specified by its OID and the name of the containing system catalog. This is just like obj_description except that it is used for retrieving comments on shared objects (e.g. databases).

+		Stable
+ diff --git a/src/current/_includes/cockroach-generated/release-25.4/sql/operators.md b/src/current/_includes/cockroach-generated/release-25.4/sql/operators.md new file mode 100644 index 00000000000..e79484b0754 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.4/sql/operators.md @@ -0,0 +1,684 @@ + + + + + +
#Return
int # intint
varbit # varbitvarbit
+ + + + +
#>Return
jsonb #> string[]jsonb
+ + + + +
#>>Return
jsonb #>> string[]string
+ + + + + + + + + +
%Return
decimal % decimaldecimal
decimal % intdecimal
float % floatfloat
int % decimaldecimal
int % intint
string % stringbool
+ + + + + + +
&Return
inet & inetinet
int & intint
varbit & varbitvarbit
+ + + + + + + + + +
&&Return
anyelement && anyelementbool
box2d && box2dbool
box2d && geometrybool
geometry && box2dbool
geometry && geometrybool
inet && inetbool
+ + + + + + + + + + + + + + + +
*Return
decimal * decimaldecimal
decimal * intdecimal
decimal * intervalinterval
float * floatfloat
float * intervalinterval
int * decimaldecimal
int * intint
int * intervalinterval
interval * decimalinterval
interval * floatinterval
interval * intinterval
vector * vectorvector
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Return
+decimaldecimal
+floatfloat
+intint
+intervalinterval
date + intdate
date + intervaltimestamp
date + timetimestamp
date + timetztimestamptz
decimal + decimaldecimal
decimal + intdecimal
decimal + pg_lsnpg_lsn
float + floatfloat
inet + intinet
int + datedate
int + decimaldecimal
int + inetinet
int + intint
interval + datetimestamp
interval + intervalinterval
interval + timetime
interval + timestamptimestamp
interval + timestamptztimestamptz
interval + timetztimetz
pg_lsn + decimalpg_lsn
time + datetimestamp
time + intervaltime
timestamp + intervaltimestamp
timestamptz + intervaltimestamptz
timetz + datetimestamptz
timetz + intervaltimetz
vector + vectorvector
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
-Return
-decimaldecimal
-floatfloat
-intint
-intervalinterval
date - dateint
date - intdate
date - intervaltimestamp
date - timetimestamp
decimal - decimaldecimal
decimal - intdecimal
float - floatfloat
inet - inetint
inet - intinet
int - decimaldecimal
int - intint
interval - intervalinterval
jsonb - intjsonb
jsonb - stringjsonb
jsonb - string[]jsonb
pg_lsn - decimalpg_lsn
pg_lsn - pg_lsndecimal
time - intervaltime
time - timeinterval
timestamp - intervaltimestamp
timestamp - timestampinterval
timestamp - timestamptzinterval
timestamptz - intervaltimestamptz
timestamptz - timestampinterval
timestamptz - timestamptzinterval
timetz - intervaltimetz
vector - vectorvector
+ + + + + +
->Return
jsonb -> intjsonb
jsonb -> stringjsonb
+ + + + + +
->>Return
jsonb ->> intstring
jsonb ->> stringstring
+ + + + + + + + + + +
/Return
decimal / decimaldecimal
decimal / intdecimal
float / floatfloat
int / decimaldecimal
int / intdecimal
interval / floatinterval
interval / intinterval
+ + + + + + + + +
//Return
decimal // decimaldecimal
decimal // intdecimal
float // floatfloat
int // decimaldecimal
int // intint
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<Return
anyenum < anyenumbool
bool < boolbool
bool[] < bool[]bool
box2d < box2dbool
bpchar < bpcharbool
bytes < bytesbool
bytes[] < bytes[]bool
collatedstring < collatedstringbool
collatedstring{*} < collatedstring{*}bool
date < datebool
date < timestampbool
date < timestamptzbool
date[] < date[]bool
decimal < decimalbool
decimal < floatbool
decimal < intbool
decimal[] < decimal[]bool
float < decimalbool
float < floatbool
float < intbool
float[] < float[]bool
geography < geographybool
geometry < geometrybool
inet < inetbool
inet[] < inet[]bool
int < decimalbool
int < floatbool
int < intbool
int < oidbool
int[] < int[]bool
interval < intervalbool
interval[] < interval[]bool
jsonb < jsonbbool
ltree < ltreebool
oid < intbool
oid < oidbool
pg_lsn < pg_lsnbool
refcursor < refcursorbool
string < stringbool
string[] < string[]bool
time < timebool
time < timetzbool
time[] < time[]bool
timestamp < datebool
timestamp < timestampbool
timestamp < timestamptzbool
timestamp[] < timestamp[]bool
timestamptz < datebool
timestamptz < timestampbool
timestamptz < timestamptzbool
timestamptz < timestamptzbool
timetz < timebool
timetz < timetzbool
tuple < tuplebool
uuid < uuidbool
uuid[] < uuid[]bool
varbit < varbitbool
vector < vectorbool
+ + + + +
<#>Return
vector <#> vectorfloat
+ + + + +
<->Return
vector <-> vectorfloat
+ + + + + + +
<<Return
inet << inetbool
int << intint
varbit << intvarbit
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<=Return
anyenum <= anyenumbool
bool <= boolbool
bool[] <= bool[]bool
box2d <= box2dbool
bpchar <= bpcharbool
bytes <= bytesbool
bytes[] <= bytes[]bool
collatedstring <= collatedstringbool
collatedstring{*} <= collatedstring{*}bool
date <= datebool
date <= timestampbool
date <= timestamptzbool
date[] <= date[]bool
decimal <= decimalbool
decimal <= floatbool
decimal <= intbool
decimal[] <= decimal[]bool
float <= decimalbool
float <= floatbool
float <= intbool
float[] <= float[]bool
geography <= geographybool
geometry <= geometrybool
inet <= inetbool
inet[] <= inet[]bool
int <= decimalbool
int <= floatbool
int <= intbool
int <= oidbool
int[] <= int[]bool
interval <= intervalbool
interval[] <= interval[]bool
jsonb <= jsonbbool
ltree <= ltreebool
oid <= intbool
oid <= oidbool
pg_lsn <= pg_lsnbool
refcursor <= refcursorbool
string <= stringbool
string[] <= string[]bool
time <= timebool
time <= timetzbool
time[] <= time[]bool
timestamp <= datebool
timestamp <= timestampbool
timestamp <= timestamptzbool
timestamp[] <= timestamp[]bool
timestamptz <= datebool
timestamptz <= timestampbool
timestamptz <= timestamptzbool
timestamptz <= timestamptzbool
timetz <= timebool
timetz <= timetzbool
tuple <= tuplebool
uuid <= uuidbool
uuid[] <= uuid[]bool
varbit <= varbitbool
vector <= vectorbool
+ + + + +
<=>Return
vector <=> vectorfloat
+ + + + + + +
<@Return
anyelement <@ anyelementbool
jsonb <@ jsonbbool
ltree <@ ltreebool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
=Return
anyenum = anyenumbool
bool = boolbool
bool[] = bool[]bool
box2d = box2dbool
bpchar = bpcharbool
bytes = bytesbool
bytes[] = bytes[]bool
collatedstring = collatedstringbool
collatedstring{*} = collatedstring{*}bool
date = datebool
date = timestampbool
date = timestamptzbool
date[] = date[]bool
decimal = decimalbool
decimal = floatbool
decimal = intbool
decimal[] = decimal[]bool
float = decimalbool
float = floatbool
float = intbool
float[] = float[]bool
geography = geographybool
geometry = geometrybool
inet = inetbool
inet[] = inet[]bool
int = decimalbool
int = floatbool
int = intbool
int = oidbool
int[] = int[]bool
interval = intervalbool
interval[] = interval[]bool
jsonb = jsonbbool
ltree = ltreebool
oid = intbool
oid = oidbool
pg_lsn = pg_lsnbool
refcursor = refcursorbool
string = stringbool
string[] = string[]bool
time = timebool
time = timetzbool
time[] = time[]bool
timestamp = datebool
timestamp = timestampbool
timestamp = timestamptzbool
timestamp[] = timestamp[]bool
timestamptz = datebool
timestamptz = timestampbool
timestamptz = timestamptzbool
timestamptz = timestamptzbool
timetz = timebool
timetz = timetzbool
tsquery = tsquerybool
tsvector = tsvectorbool
tuple = tuplebool
uuid = uuidbool
uuid[] = uuid[]bool
varbit = varbitbool
vector = vectorbool
+ + + + + + +
>>Return
inet >> inetbool
int >> intint
varbit >> intvarbit
+ + + + +
?Return
jsonb ? stringbool
+ + + + +
?&Return
jsonb ?& string[]bool
+ + + + +
?<@Return
ltree ?<@ ltreeltree
+ + + + +
?@>Return
ltree ?@> ltreeltree
+ + + + +
?|Return
jsonb ?| string[]bool
+ + + + + + +
@>Return
anyelement @> anyelementbool
jsonb @> jsonbbool
ltree @> ltreebool
+ + + + + +
@@Return
tsquery @@ tsvectorbool
tsvector @@ tsquerybool
+ + + + +
ILIKEReturn
string ILIKE stringbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
INReturn
anyenum IN tuplebool
bool IN tuplebool
box2d IN tuplebool
bpchar IN tuplebool
bytes IN tuplebool
collatedstring IN tuplebool
date IN tuplebool
decimal IN tuplebool
float IN tuplebool
geography IN tuplebool
geometry IN tuplebool
inet IN tuplebool
int IN tuplebool
interval IN tuplebool
jsonb IN tuplebool
ltree IN tuplebool
oid IN tuplebool
pg_lsn IN tuplebool
refcursor IN tuplebool
string IN tuplebool
time IN tuplebool
timestamp IN tuplebool
timestamptz IN tuplebool
timetz IN tuplebool
tuple IN tuplebool
uuid IN tuplebool
varbit IN tuplebool
vector IN tuplebool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IS NOT DISTINCT FROMReturn
anyelement IS NOT DISTINCT FROM unknownbool
anyenum IS NOT DISTINCT FROM anyenumbool
bool IS NOT DISTINCT FROM boolbool
bool[] IS NOT DISTINCT FROM bool[]bool
box2d IS NOT DISTINCT FROM box2dbool
bpchar IS NOT DISTINCT FROM bpcharbool
bytes IS NOT DISTINCT FROM bytesbool
bytes[] IS NOT DISTINCT FROM bytes[]bool
collatedstring IS NOT DISTINCT FROM collatedstringbool
collatedstring{*} IS NOT DISTINCT FROM collatedstring{*}bool
date IS NOT DISTINCT FROM datebool
date IS NOT DISTINCT FROM timestampbool
date IS NOT DISTINCT FROM timestamptzbool
date[] IS NOT DISTINCT FROM date[]bool
decimal IS NOT DISTINCT FROM decimalbool
decimal IS NOT DISTINCT FROM floatbool
decimal IS NOT DISTINCT FROM intbool
decimal[] IS NOT DISTINCT FROM decimal[]bool
float IS NOT DISTINCT FROM decimalbool
float IS NOT DISTINCT FROM floatbool
float IS NOT DISTINCT FROM intbool
float[] IS NOT DISTINCT FROM float[]bool
geography IS NOT DISTINCT FROM geographybool
geometry IS NOT DISTINCT FROM geometrybool
inet IS NOT DISTINCT FROM inetbool
inet[] IS NOT DISTINCT FROM inet[]bool
int IS NOT DISTINCT FROM decimalbool
int IS NOT DISTINCT FROM floatbool
int IS NOT DISTINCT FROM intbool
int IS NOT DISTINCT FROM oidbool
int[] IS NOT DISTINCT FROM int[]bool
interval IS NOT DISTINCT FROM intervalbool
interval[] IS NOT DISTINCT FROM interval[]bool
jsonb IS NOT DISTINCT FROM jsonbbool
jsonpath IS NOT DISTINCT FROM jsonpathbool
ltree IS NOT DISTINCT FROM ltreebool
oid IS NOT DISTINCT FROM intbool
oid IS NOT DISTINCT FROM oidbool
pg_lsn IS NOT DISTINCT FROM pg_lsnbool
refcursor IS NOT DISTINCT FROM refcursorbool
string IS NOT DISTINCT FROM stringbool
string[] IS NOT DISTINCT FROM string[]bool
time IS NOT DISTINCT FROM timebool
time IS NOT DISTINCT FROM timetzbool
time[] IS NOT DISTINCT FROM time[]bool
timestamp IS NOT DISTINCT FROM datebool
timestamp IS NOT DISTINCT FROM timestampbool
timestamp IS NOT DISTINCT FROM timestamptzbool
timestamp[] IS NOT DISTINCT FROM timestamp[]bool
timestamptz IS NOT DISTINCT FROM datebool
timestamptz IS NOT DISTINCT FROM timestampbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timetz IS NOT DISTINCT FROM timebool
timetz IS NOT DISTINCT FROM timetzbool
tsquery IS NOT DISTINCT FROM tsquerybool
tsvector IS NOT DISTINCT FROM tsvectorbool
tuple IS NOT DISTINCT FROM tuplebool
unknown IS NOT DISTINCT FROM unknownbool
unknown IS NOT DISTINCT FROM voidbool
uuid IS NOT DISTINCT FROM uuidbool
uuid[] IS NOT DISTINCT FROM uuid[]bool
varbit IS NOT DISTINCT FROM varbitbool
vector IS NOT DISTINCT FROM vectorbool
void IS NOT DISTINCT FROM unknownbool
+ + + + + +
LIKEReturn
collatedstring LIKE collatedstringbool
string LIKE stringbool
+ + + + +
SIMILAR TOReturn
string SIMILAR TO stringbool
+ + + + + + + + +
^Return
decimal ^ decimaldecimal
decimal ^ intdecimal
float ^ floatfloat
int ^ decimaldecimal
int ^ intint
+ + + + + + +
|Return
inet | inetinet
int | intint
varbit | varbitvarbit
+ + + + + +
|/Return
|/decimaldecimal
|/floatfloat
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
||Return
bool || bool[]bool[]
bool || stringstring
bool[] || boolbool[]
bool[] || bool[]bool[]
box2d || box2dbox2d
box2d || stringstring
bytes || bytesbytes
bytes || bytes[]bytes[]
bytes[] || bytesbytes[]
bytes[] || bytes[]bytes[]
date || date[]date[]
date || stringstring
date[] || datedate[]
date[] || date[]date[]
decimal || decimal[]decimal[]
decimal || stringstring
decimal[] || decimaldecimal[]
decimal[] || decimal[]decimal[]
float || float[]float[]
float || stringstring
float[] || floatfloat[]
float[] || float[]float[]
geography || geographygeography
geography || stringstring
geometry || geometrygeometry
geometry || stringstring
inet || inet[]inet[]
inet || stringstring
inet[] || inetinet[]
inet[] || inet[]inet[]
int || int[]int[]
int || stringstring
int[] || intint[]
int[] || int[]int[]
interval || interval[]interval[]
interval || stringstring
interval[] || intervalinterval[]
interval[] || interval[]interval[]
jsonb || jsonbjsonb
jsonb || stringstring
ltree || ltreeltree
ltree || stringstring
oid || oidoid
oid || stringstring
pg_lsn || pg_lsnpg_lsn
pg_lsn || stringstring
refcursor || refcursorrefcursor
refcursor || stringstring
string || boolstring
string || box2dstring
string || datestring
string || decimalstring
string || floatstring
string || geographystring
string || geometrystring
string || inetstring
string || intstring
string || intervalstring
string || jsonbstring
string || ltreestring
string || oidstring
string || pg_lsnstring
string || refcursorstring
string || stringstring
string || string[]string[]
string || timestring
string || timestampstring
string || timestamptzstring
string || timetzstring
string || tuplestring
string || uuidstring
string || varbitstring
string[] || stringstring[]
string[] || string[]string[]
time || stringstring
time || time[]time[]
time[] || timetime[]
time[] || time[]time[]
timestamp || stringstring
timestamp || timestamp[]timestamp[]
timestamp[] || timestamptimestamp[]
timestamp[] || timestamp[]timestamp[]
timestamptz || stringstring
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timetz || stringstring
timetz || timetztimetz
tuple || stringstring
uuid || stringstring
uuid || uuid[]uuid[]
uuid[] || uuiduuid[]
uuid[] || uuid[]uuid[]
varbit || stringstring
varbit || varbitvarbit
+ + + + + +
||/Return
||/decimaldecimal
||/floatfloat
+ + + + + + + + + + + +
~Return
~inetinet
~intint
~varbitvarbit
box2d ~ box2dbool
box2d ~ geometrybool
geometry ~ box2dbool
geometry ~ geometrybool
string ~ stringbool
+ + + + +
~*Return
string ~* stringbool
diff --git a/src/current/_includes/cockroach-generated/release-25.4/sql/window_functions.md b/src/current/_includes/cockroach-generated/release-25.4/sql/window_functions.md new file mode 100644 index 00000000000..321cc02ccf9 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-25.4/sql/window_functions.md @@ -0,0 +1,431 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cume_dist() → float

Calculates the relative rank of the current row: (number of rows preceding or peer with current row) / (total rows).

+		Immutable
dense_rank() → int

Calculates the rank of the current row without gaps; this function counts peer groups.

+		Immutable
first_value(val: bool) → bool

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: bytes) → bytes

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: date) → date

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: decimal) → decimal

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: float) → float

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: inet) → inet

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: int) → int

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: interval) → interval

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: string) → string

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: time) → time

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: uuid) → uuid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: box2d) → box2d

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geography) → geography

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geometry) → geometry

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: ltree) → ltree

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: oid) → oid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timetz) → timetz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: varbit) → varbit

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
lag(val: bool) → bool

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: bytes) → bytes

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: date) → date

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: date, n: int) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: decimal) → decimal

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: float) → float

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: float, n: int) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: inet) → inet

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: int) → int

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: int, n: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: interval) → interval

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: string) → string

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: string, n: int) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: time) → time

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: time, n: int) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamp) → timestamp

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz) → timestamptz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: uuid) → uuid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: box2d) → box2d

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geography) → geography

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geometry) → geometry

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: jsonb) → jsonb

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: ltree) → ltree

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: ltree, n: int) → ltree

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: ltree, n: int, default: ltree) → ltree

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: oid) → oid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn) → pg_lsn

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: refcursor) → refcursor

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timetz) → timetz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: varbit) → varbit

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
last_value(val: bool) → bool

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: bytes) → bytes

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: date) → date

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: decimal) → decimal

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: float) → float

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: inet) → inet

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: int) → int

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: interval) → interval

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: string) → string

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: time) → time

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: uuid) → uuid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: box2d) → box2d

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geography) → geography

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geometry) → geometry

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: ltree) → ltree

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: oid) → oid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timetz) → timetz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: varbit) → varbit

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
lead(val: bool) → bool

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: bytes) → bytes

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: date) → date

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: date, n: int) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: decimal) → decimal

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: float) → float

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: float, n: int) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: inet) → inet

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: int) → int

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: int, n: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: interval) → interval

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: string) → string

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: string, n: int) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: time) → time

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: time, n: int) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamp) → timestamp

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz) → timestamptz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: uuid) → uuid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: box2d) → box2d

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geography) → geography

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geometry) → geometry

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: jsonb) → jsonb

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: ltree) → ltree

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: ltree, n: int) → ltree

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: ltree, n: int, default: ltree) → ltree

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: oid) → oid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn) → pg_lsn

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: refcursor) → refcursor

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timetz) → timetz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: varbit) → varbit

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
nth_value(val: bool, n: int) → bool

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: bytes, n: int) → bytes

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: date, n: int) → date

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: decimal, n: int) → decimal

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: float, n: int) → float

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: inet, n: int) → inet

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: int, n: int) → int

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: interval, n: int) → interval

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: string, n: int) → string

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: time, n: int) → time

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: uuid, n: int) → uuid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: box2d, n: int) → box2d

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geography, n: int) → geography

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geometry, n: int) → geometry

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: ltree, n: int) → ltree

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: oid, n: int) → oid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timetz, n: int) → timetz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: varbit, n: int) → varbit

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
ntile(n: int) → int

Calculates an integer ranging from 1 to n, dividing the partition as equally as possible.

+		Immutable
percent_rank() → float

Calculates the relative rank of the current row: (rank - 1) / (total rows - 1).

+		Immutable
rank() → int

Calculates the rank of the current row with gaps; same as row_number of its first peer.

+		Immutable
row_number() → int

Calculates the number of the current row within its partition, counting from 1.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-26.1/eventlog.md b/src/current/_includes/cockroach-generated/release-26.1/eventlog.md new file mode 100644 index 00000000000..2edf5ed39f4 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-26.1/eventlog.md @@ -0,0 +1,3874 @@ +Certain notable events are reported using a structured format. +Commonly, these notable events are also copied to the table +`system.eventlog`, unless the cluster setting +`server.eventlog.enabled` is unset. + +Additionally, notable events are copied to specific external logging +channels in log messages, where they can be collected for further processing. + +The sections below document the possible notable event types +in this version of CockroachDB. For each event type, a table +documents the possible fields. A field may be omitted from +an event if its value is empty or zero. + +A field is also considered "Sensitive" if it may contain +application-specific information or personally identifiable information (PII). In that case, +the copy of the event sent to the external logging channel +will contain redaction markers in a format that is compatible +with the redaction facilities in [`cockroach debug zip`](cockroach-debug-zip.html) +and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html), +provided the `redactable` functionality is enabled on the logging sink. + +Events not documented on this page will have an unstructured format in log messages. + +## Changefeed telemetry events + +Events in this category pertain to changefeed usage and metrics. + +Events in this category are logged to the `CHANGEFEED` channel. + + +### `alter_changefeed` + +An event of type `alter_changefeed` is an event for any ALTER CHANGEFEED statements that are run. + +Note: in version 26.1, these events will be moved to the `CHANGEFEED` channel. +To test compatability before this, set the cluster setting +`log.channel_compatibility_mode.enabled` to false. This will send the +events to `CHANGEFEED` instead of `TELEMETRY`. + + +| Field | Description | Sensitive | +|--|--|--| +| `PreviousDescription` | The description of the changefeed job before the ALTER CHANGEFEED. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `changefeed_canceled` + +An event of type `changefeed_canceled` is an event for any changefeed cancellations. + +Note: in version 26.1, these events will be moved to the `CHANGEFEED` channel. +To test compatability before this, set the cluster setting +`log.channel_compatibility_mode.enabled` to false. This will send the +events to `CHANGEFEED` instead of `TELEMETRY`. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `changefeed_emitted_bytes` + +An event of type `changefeed_emitted_bytes` is an event representing the bytes emitted by a changefeed over an interval. + +Note: in version 26.1, these events will be moved to the `CHANGEFEED` channel. +To test compatability before this, set the cluster setting +`log.channel_compatibility_mode.enabled` to false. This will send the +events to `CHANGEFEED` instead of `TELEMETRY`. + + +| Field | Description | Sensitive | +|--|--|--| +| `EmittedBytes` | The number of bytes emitted. | no | +| `EmittedMessages` | The number of messages emitted. | no | +| `LoggingInterval` | The time period in nanoseconds between emitting telemetry events of this type (per-aggregator). | no | +| `Closing` | Flag to indicate that the changefeed is closing. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `changefeed_failed` + +An event of type `changefeed_failed` is an event for any changefeed failure since the plan hook +was triggered. + +Note: in version 26.1, these events will be moved to the `CHANGEFEED` channel. +To test compatability before this, set the cluster setting +`log.channel_compatibility_mode.enabled` to false. This will send the +events to `CHANGEFEED` instead of `TELEMETRY`. + + +| Field | Description | Sensitive | +|--|--|--| +| `FailureType` | The reason / environment with which the changefeed failed (ex: connection_closed, changefeed_behind). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `create_changefeed` + +An event of type `create_changefeed` is an event for any CREATE CHANGEFEED query that +successfully starts running. Failed CREATE statements will show up as +ChangefeedFailed events. + +Note: in version 26.1, these events moved to the `CHANGEFEED` channel. +To test compatability prior to this, set the cluster setting +`log.channel_compatibility_mode.enabled` to true. This will send the +events to `TELEMETRY` instead of `CHANGEFEED`. + + +| Field | Description | Sensitive | +|--|--|--| +| `Transformation` | Flag representing whether the changefeed is using CDC queries. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +## Cluster-level events + +Events in this category pertain to an entire cluster and are +not relative to any particular tenant. + +In a multi-tenant setup, the `system.eventlog` table for individual +tenants cannot contain a copy of cluster-level events; conversely, +the `system.eventlog` table in the system tenant cannot contain the +SQL-level events for individual tenants. + +Events in this category are logged to the `OPS` channel. + + +### `certs_reload` + +An event of type `certs_reload` is recorded when the TLS certificates are +reloaded/rotated from disk. + + +| Field | Description | Sensitive | +|--|--|--| +| `Success` | Whether the operation completed without errors. | no | +| `ErrorMessage` | If an error was encountered, the text of the error. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `disk_slowness_cleared` + +An event of type `disk_slowness_cleared` is recorded when disk slowness in a store has cleared. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `disk_slowness_detected` + +An event of type `disk_slowness_detected` is recorded when a store observes disk slowness +events. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `low_disk_space` + +An event of type `low_disk_space` is emitted when a store is reaching capacity, as we reach +certain thresholds. It is emitted periodically while we are in a low disk +state. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | +| `PercentThreshold` | The free space percent threshold that we went under. | no | +| `AvailableBytes` | | no | +| `TotalBytes` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `node_decommissioned` + +An event of type `node_decommissioned` is recorded when a node is marked as +decommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_decommissioning` + +An event of type `node_decommissioning` is recorded when a node is marked as +decommissioning. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_join` + +An event of type `node_join` is recorded when a node joins the cluster. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_recommissioned` + +An event of type `node_recommissioned` is recorded when a decommissioning node is +recommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_restart` + +An event of type `node_restart` is recorded when an existing node rejoins the cluster +after being offline. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_connection_timeout` + +An event of type `node_shutdown_connection_timeout` is recorded when SQL connections remain open +during shutdown, after waiting for the server.shutdown.connections.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still open after waiting for the client to close them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.connections.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_transaction_timeout` + +An event of type `node_shutdown_transaction_timeout` is recorded when SQL transactions remain open +during shutdown, after waiting for the server.shutdown.transactions.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still running SQL transactions after waiting for the client to end them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.transactions.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `tenant_shared_service_start` + +An event of type `tenant_shared_service_start` is recorded when a tenant server +is started inside the same process as the KV layer. + + +| Field | Description | Sensitive | +|--|--|--| +| `OK` | Whether the startup was successful. | no | +| `ErrorText` | If the startup failed, the text of the error. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +### `tenant_shared_service_stop` + +An event of type `tenant_shared_service_stop` is recorded when a tenant server +is shut down inside the same process as the KV layer. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +## Contention events + +Aggregated information about contention events. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `aggregated_contention_info` + +An event of type `aggregated_contention_info` is recorded periodically when contention events +are resolved. + + +| Field | Description | Sensitive | +|--|--|--| +| `WaitingStmtFingerprintId` | | no | +| `WaitingTxnFingerprintId` | | no | +| `BlockingTxnFingerprintId` | | no | +| `ContendedKey` | | partially | +| `Duration` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Debugging events + +Events in this category pertain to debugging operations performed by +operators or (more commonly) Cockroach Labs employees. These operations can +e.g. directly access and mutate internal state, breaking system invariants. + +Events in this category are logged to the `OPS` channel. + + +### `debug_recover_replica` + +An event of type `debug_recover_replica` is recorded when unsafe loss of quorum recovery is performed. + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `StoreID` | | no | +| `SurvivorReplicaID` | | no | +| `UpdatedReplicaID` | | no | +| `StartKey` | | yes | +| `EndKey` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +### `debug_send_kv_batch` + +An event of type `debug_send_kv_batch` is recorded when an arbitrary KV BatchRequest is submitted +to the cluster via the `debug send-kv-batch` CLI command. + + +| Field | Description | Sensitive | +|--|--|--| +| `BatchRequest` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +## Health events + +Events in this category pertain to the health of one or more servers. + +Events in this category are logged to the `HEALTH` channel. + + +### `hot_ranges_stats` + +An event of type `hot_ranges_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `Qps` | | no | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | yes | +| `LeaseholderNodeID` | LeaseholderNodeID indicates the Node ID that is the current leaseholder for the given range. | no | +| `WritesPerSecond` | Writes per second is the recent number of keys written per second on this range. | no | +| `ReadsPerSecond` | Reads per second is the recent number of keys read per second on this range. | no | +| `WriteBytesPerSecond` | Write bytes per second is the recent number of bytes written per second on this range. | no | +| `ReadBytesPerSecond` | Read bytes per second is the recent number of bytes read per second on this range. | no | +| `CPUTimePerSecond` | CPU time per second is the recent cpu usage in nanoseconds of this range. | no | +| `Databases` | Databases for the range. | no | +| `Tables` | Tables for the range | no | +| `Indexes` | Indexes for the range | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `runtime_stats` + +An event of type `runtime_stats` is recorded every 10 seconds as server health metrics. + + +| Field | Description | Sensitive | +|--|--|--| +| `MemRSSBytes` | The process resident set size. Expressed as bytes. | no | +| `GoroutineCount` | The number of goroutines. | no | +| `MemStackSysBytes` | The stack system memory used. Expressed as bytes. | no | +| `GoAllocBytes` | The memory allocated by Go. Expressed as bytes. | no | +| `GoTotalBytes` | The total memory allocated by Go but not released. Expressed as bytes. | no | +| `GoStatsStaleness` | The staleness of the Go memory statistics. Expressed in seconds. | no | +| `HeapFragmentBytes` | The amount of heap fragmentation. Expressed as bytes. | no | +| `HeapReservedBytes` | The amount of heap reserved. Expressed as bytes. | no | +| `HeapReleasedBytes` | The amount of heap released. Expressed as bytes. | no | +| `CGoAllocBytes` | The memory allocated outside of Go. Expressed as bytes. | no | +| `CGoTotalBytes` | The total memory allocated outside of Go but not released. Expressed as bytes. | no | +| `CGoCallRate` | The total number of calls outside of Go over time. Expressed as operations per second. | no | +| `CPUUserPercent` | The user CPU percentage. | no | +| `CPUSysPercent` | The system CPU percentage. | no | +| `GCPausePercent` | The GC pause percentage. | no | +| `GCRunCount` | The total number of GC runs. | no | +| `NetHostRecvBytes` | The bytes received on all network interfaces since this process started. | no | +| `NetHostSendBytes` | The bytes sent on all network interfaces since this process started. | no | +| `GoLimitBytes` | The soft Go memory limit in bytes. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Job events + +Events in this category pertain to long-running jobs that are orchestrated by +a node's job registry. These system processes can create and/or modify stored +objects during the course of their execution. + +A job might choose to emit multiple events during its execution when +transitioning from one "state" to another. +Egs: IMPORT/RESTORE will emit events on job creation and successful +completion. If the job fails, events will be emitted on job creation, +failure, and successful revert. + +Events in this category are logged to the `OPS` channel. + + +### `import` + +An event of type `import` is recorded when an import job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `restore` + +An event of type `restore` is recorded when a restore job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `status_change` + +An event of type `status_change` is recorded when a job changes statuses. + + +| Field | Description | Sensitive | +|--|--|--| +| `JobID` | The ID of the job that is changing statuses. | no | +| `JobType` | The type of the job that is changing statuses. | no | +| `Description` | A human parsable description of the status change | partially | +| `PreviousStatus` | The status that the job is transitioning out of | no | +| `NewStatus` | The status that the job has transitioned into | no | +| `RunNum` | The run number of the job. | no | +| `Error` | An error that may have occurred while the job was running. | yes | +| `FinalResumeErr` | An error that occurred that requires the job to be reverted. | yes | +| `User` | User is the owner of the job. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Miscellaneous SQL events + +Events in this category report miscellaneous SQL events. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own system.eventlog table. + +Events in this category are logged to the `OPS` channel. + + +### `rewrite_inline_hints` + +An event of type `rewrite_inline_hints` is recorded when a new inline-hints rewrite rule is added +via information_schema.crdb_rewrite_inline_hints. + + +| Field | Description | Sensitive | +|--|--|--| +| `StatementFingerprint` | The target statement fingerprint for which inline hints are being rewritten. | no | +| `DonorSQL` | The donor statement providing the inline hints. | no | +| `HintID` | The hint ID of the newly created statement hint. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `set_cluster_setting` + +An event of type `set_cluster_setting` is recorded when a cluster setting is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | +| `DefaultValue` | The current default value of the cluster setting. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `set_tenant_cluster_setting` + +An event of type `set_tenant_cluster_setting` is recorded when a cluster setting override +is changed, either for another tenant or for all tenants. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | +| `TenantId` | The target Tenant ID. Empty if targeting all tenants. | no | +| `AllTenants` | Whether the override applies to all tenants. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +## SQL Access Audit Events + +Events in this category are generated when a table has been +marked as audited via `ALTER TABLE ... EXPERIMENTAL_AUDIT SET`. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SENSITIVE_ACCESS` channel. + + +### `admin_query` + +An event of type `admin_query` is recorded when a user with admin privileges (the user +is directly or indirectly a member of the admin role) executes a query. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `role_based_audit_event` + +An event of type `role_based_audit_event` is an audit event recorded when an executed query belongs to a user whose role +membership(s) correspond to any role that is enabled to emit an audit log via the sql.log.user_audit +cluster setting. + + +| Field | Description | Sensitive | +|--|--|--| +| `Role` | The configured audit role that emitted this log. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sensitive_table_access` + +An event of type `sensitive_table_access` is recorded when an access is performed to +a table marked as audited. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table being audited. | yes | +| `AccessMode` | How the table was accessed (r=read / rw=read/write). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `unsafe_internals_accessed` + +UnsafeInternalsAccess is recorded when a query accesses unsafe internals +using the allow_unsafe_internals override. + + +| Field | Description | Sensitive | +|--|--|--| +| `Query` | The query that triggered the unsafe internals access. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `unsafe_internals_denied` + +An event of type `unsafe_internals_denied` is recorded when a query attempts to access unsafe internals +but lacks the appropriate session variables. + + +| Field | Description | Sensitive | +|--|--|--| +| `Query` | The query that triggered the unsafe internals access. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +## SQL Execution Log + +Events in this category report executed queries. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `query_execute` + +An event of type `query_execute` is recorded when a query is executed, +and the cluster setting `sql.log.all_statements.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +## SQL Logical Schema Changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the SQL logical +schema. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SQL_SCHEMA` channel. + + +### `alter_database_add_region` + +An event of type `alter_database_add_region` is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `RegionName` | The region being added. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_database_drop_region` + +AlterDatabaseAddRegion is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `RegionName` | The region being dropped. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_database_placement` + +An event of type `alter_database_placement` is recorded when the database placement is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `Placement` | The new placement policy. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_database_primary_region` + +An event of type `alter_database_primary_region` is recorded when a primary region is added/modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `PrimaryRegionName` | The new primary region. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_database_set_zone_config_extension` + +An event of type `alter_database_set_zone_config_extension` is recorded when a zone config extension is changed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `alter_database_survival_goal` + +An event of type `alter_database_survival_goal` is recorded when the survival goal is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `SurvivalGoal` | The new survival goal | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_function_options` + +An event of type `alter_function_options` is recorded when a user-defined function's options are +altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the affected function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_index` + +An event of type `alter_index` is recorded when an index is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_index_visible` + +AlterIndex is recorded when an index visibility is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `NotVisible` | Set true if index is not visible. NOTE: THIS FIELD IS DEPRECATED in favor of invisibility. | no | +| `Invisibility` | The new invisibility of the affected index. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_sequence` + +An event of type `alter_sequence` is recorded when a sequence is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_table` + +An event of type `alter_table` is recorded when a table is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update, if any. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_type` + +EventAlterType is recorded when a user-defined type is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_column` + +An event of type `comment_on_column` is recorded when a column is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected column. | no | +| `ColumnName` | The affected column. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_constraint` + +An event of type `comment_on_constraint` is recorded when an constraint is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected constraint. | no | +| `ConstraintName` | The name of the affected constraint. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_database` + +CommentOnTable is recorded when a database is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_index` + +An event of type `comment_on_index` is recorded when an index is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_schema` + + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | Name of the affected schema. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_table` + +An event of type `comment_on_table` is recorded when a table is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_type` + +An event of type `comment_on_type` is recorded when a type is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_database` + +An event of type `create_database` is recorded when a database is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the new database. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_function` + +An event of type `create_function` is recorded when a user-defined function is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the created function. | no | +| `IsReplace` | If the new function is a replace of an existing function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_index` + +An event of type `create_index` is recorded when an index is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the new index. | no | +| `IndexName` | The name of the new index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_policy` + +An event of type `create_policy` is recorded when a policy is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the policy's table. | no | +| `PolicyName` | Name of the created policy. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_schema` + +An event of type `create_schema` is recorded when a schema is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the new schema. | no | +| `Owner` | The name of the owner for the new schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_sequence` + +An event of type `create_sequence` is recorded when a sequence is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the new sequence. | no | +| `Owner` | The name of the owner for the new sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_statistics` + +An event of type `create_statistics` is recorded when statistics are collected for a +table. + +Events of this type are only collected when the cluster setting +`sql.stats.post_events.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table for which the statistics were created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_table` + +An event of type `create_table` is recorded when a table is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the new table. | no | +| `Owner` | The name of the owner for the new table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_trigger` + +An event of type `create_trigger` is recorded when a trigger is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the trigger's table. | no | +| `TriggerName` | Name of the created trigger. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_type` + +An event of type `create_type` is recorded when a user-defined type is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the new type. | no | +| `Owner` | The name of the owner for the new type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_view` + +An event of type `create_view` is recorded when a view is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the new view. | no | +| `Owner` | The name of the owner of the new view. | no | +| `ViewQuery` | The SQL selection clause used to define the view. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_database` + +An event of type `drop_database` is recorded when a database is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | no | +| `DroppedSchemaObjects` | The names of the schemas dropped by a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_function` + +An event of type `drop_function` is recorded when a user-defined function is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the dropped function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_index` + +An event of type `drop_index` is recorded when an index is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_policy` + +An event of type `drop_policy` is recorded when a policy is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the policy's table. | no | +| `PolicyName` | Name of the dropped policy. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_schema` + +An event of type `drop_schema` is recorded when a schema is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_sequence` + +An event of type `drop_sequence` is recorded when a sequence is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_table` + +An event of type `drop_table` is recorded when a table is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_trigger` + +An event of type `drop_trigger` is recorded when a trigger is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the trigger's table. | no | +| `TriggerName` | Name of the dropped trigger. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_type` + +An event of type `drop_type` is recorded when a user-defined type is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_view` + +An event of type `drop_view` is recorded when a view is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the affected view. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `finish_schema_change` + +An event of type `finish_schema_change` is recorded when a previously initiated schema +change has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to complete. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `finish_schema_change_rollback` + +An event of type `finish_schema_change_rollback` is recorded when a previously +initiated schema change rollback has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to rollback. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `force_delete_table_data_entry` + + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `refresh_materialized_view` + +An event of type `refresh_materialized_view` is recorded when a materialized view is refreshed. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the materialized view being refreshed. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `rename_database` + +An event of type `rename_database` is recorded when a database is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The old name of the affected database. | no | +| `NewDatabaseName` | The new name of the affected database. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `rename_function` + +An event of type `rename_function` is recorded when a user-defined function is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The old name of the affected function. | no | +| `NewFunctionName` | The new name of the affected function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `rename_schema` + +An event of type `rename_schema` is recorded when a schema is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The old name of the affected schema. | no | +| `NewSchemaName` | The new name of the affected schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `rename_table` + +An event of type `rename_table` is recorded when a table, sequence or view is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The old name of the affected table. | no | +| `NewTableName` | The new name of the affected table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `rename_type` + +An event of type `rename_type` is recorded when a user-defined type is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The old name of the affected type. | no | +| `NewTypeName` | The new name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `reverse_schema_change` + +An event of type `reverse_schema_change` is recorded when an in-progress schema change +encounters a problem and is reversed. + + +| Field | Description | Sensitive | +|--|--|--| +| `Error` | The error encountered that caused the schema change to be reversed. The specific format of the error is variable and can change across releases without warning. | partially | +| `SQLSTATE` | The SQLSTATE code for the error. | no | +| `LatencyNanos` | The amount of time the schema change job took before being reverted. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `set_schema` + +An event of type `set_schema` is recorded when a table, view, sequence or type's schema is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorName` | The old name of the affected descriptor. | no | +| `NewDescriptorName` | The new name of the affected descriptor. | no | +| `DescriptorType` | The descriptor type being changed (table, view, sequence, type). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `truncate_table` + +An event of type `truncate_table` is recorded when a table is truncated. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `unsafe_delete_descriptor` + +An event of type `unsafe_delete_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_delete_descriptor(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `unsafe_delete_namespace_entry` + +An event of type `unsafe_delete_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_delete_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `unsafe_upsert_descriptor` + +An event of type `unsafe_upsert_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_upsert_descriptor(). + + +| Field | Description | Sensitive | +|--|--|--| +| `PreviousDescriptor` | | yes | +| `NewDescriptor` | | yes | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `unsafe_upsert_namespace_entry` + +An event of type `unsafe_upsert_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_upsert_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `PreviousID` | | no | +| `Force` | | no | +| `FailedValidation` | | no | +| `ValidationErrors` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +## SQL Privilege changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the privilege +grants for stored objects. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `PRIVILEGES` channel. + + +### `alter_database_owner` + +An event of type `alter_database_owner` is recorded when a database's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database being affected. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_default_privileges` + +An event of type `alter_default_privileges` is recorded when default privileges are changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | +| `RoleName` | Either role_name should be populated or for_all_roles should be true. The role having its default privileges altered. | yes | +| `ForAllRoles` | Identifies if FOR ALL ROLES is used. | no | +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `alter_function_owner` + +AlterTableOwner is recorded when the owner of a user-defined function is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The name of the affected user-defined function. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_schema_owner` + +An event of type `alter_schema_owner` is recorded when a schema's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_table_owner` + +An event of type `alter_table_owner` is recorded when the owner of a table, view or sequence is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected object. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_type_owner` + +An event of type `alter_type_owner` is recorded when the owner of a user-defiend type is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `change_database_privilege` + +An event of type `change_database_privilege` is recorded when privileges are +added to / removed from a user for a database object. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_function_privilege` + + + +| Field | Description | Sensitive | +|--|--|--| +| `FuncName` | The name of the affected function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_schema_privilege` + +An event of type `change_schema_privilege` is recorded when privileges are added to / +removed from a user for a schema object. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_table_privilege` + +An event of type `change_table_privilege` is recorded when privileges are added to / removed +from a user for a table, sequence or view object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_type_privilege` + +An event of type `change_type_privilege` is recorded when privileges are added to / +removed from a user for a type object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +## SQL Session events + +Events in this category report SQL client connections +and sessions. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SESSIONS` channel. + + +### `client_authentication_failed` + +An event of type `client_authentication_failed` is reported when a client session +did not authenticate successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Reason` | The reason for the authentication failure. See below for possible values for type `AuthFailReason`. | no | +| `Detail` | The detailed error for the authentication failure. | partially | +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_info` + +An event of type `client_authentication_info` is reported for intermediate +steps during the authentication process. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used, once known. | no | +| `Info` | The authentication progress message. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_authentication_ok` + +An event of type `client_authentication_ok` is reported when a client session +was authenticated successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +### `client_connection_end` + +An event of type `client_connection_end` is reported when a client connection +is closed. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_connection_start` + +An event of type `client_connection_start` is reported when a client connection +is established. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_session_end` + +An event of type `client_session_end` is reported when a client session +is completed. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | yes | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | yes | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | yes | + +## SQL Slow Query Log + +Events in this category report slow query execution. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +In version 26.1, these events moved to the `SQL_EXEC` channel. +To test compatability prior to this, set the cluster setting +`log.channel_compatibility_mode.enabled` to true. This will send the +events to `SQL_PERF` instead of `SQL_EXEC`. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `large_row` + +An event of type `large_row` is recorded when a statement tries to write a row larger than +cluster setting `sql.guardrails.max_row_size_log` to the database. Multiple +LargeRow events will be recorded for statements writing multiple large rows. +LargeRow events are recorded before the transaction commits, so in the case +of transaction abort there will not be a corresponding row in the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `scan_row_count_misestimate` + +An event of type `scan_row_count_misestimate` is recorded when the optimizer's row count estimate +for a logical scan differs significantly from the actual number of rows read, +and cluster setting `sql.log.scan_row_count_misestimate.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The fully qualified name of the table being scanned. | no | +| `IndexName` | The name of the index being scanned. | no | +| `EstimatedRowCount` | The optimizer's estimated row count for the scan. | no | +| `ActualRowCount` | The actual number of rows read by all processors performing the scan. | no | +| `NanosSinceStatsCollected` | Time in nanoseconds that have passed since full stats were collected on the table. | no | +| `EstimatedStaleness` | Estimated fraction of stale rows in the table based on the time since stats were last collected. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `slow_query` + +An event of type `slow_query` is recorded when a query triggers the "slow query" condition. + +As of this writing, the condition requires: +- the cluster setting `sql.log.slow_query.latency_threshold` +set to a non-zero value, AND +- EITHER of the following conditions: +- the actual age of the query exceeds the configured threshold; AND/OR +- the query performs a full table/index scan AND the cluster setting +`sql.log.slow_query.experimental_full_table_scans.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit` + +An event of type `txn_rows_read_limit` is recorded when a transaction tries to read more rows than +cluster setting `sql.defaults.transaction_rows_read_log`. There will only be +a single record for a single transaction (unless it is retried) even if there +are more statement within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit` + +An event of type `txn_rows_written_limit` is recorded when a transaction tries to write more rows +than cluster setting `sql.defaults.transaction_rows_written_log`. There will +only be a single record for a single transaction (unless it is retried) even +if there are more mutation statements within the transaction that haven't +been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL Slow Query Log (Internal) + +Events in this category report slow query execution by +internal executors, i.e., when CockroachDB internally issues +SQL statements. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +In version 26.1, these events moved to the `SQL_EXEC` channel. +To test compatability prior to this, set the cluster setting +`log.channel_compatibility_mode.enabled` to true. This will send the +events to `SQL_INTERNAL_PERF` instead of `SQL_EXEC`. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `large_row_internal` + +An event of type `large_row_internal` is recorded when an internal query tries to write a row +larger than cluster settings `sql.guardrails.max_row_size_log` or +`sql.guardrails.max_row_size_err` to the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query_internal` + +An event of type `slow_query_internal` is recorded when a query triggers the "slow query" condition, +and the cluster setting `sql.log.slow_query.internal_queries.enabled` is +set. +See the documentation for the event type `slow_query` for details about +the "slow query" condition. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit_internal` + +An event of type `txn_rows_read_limit_internal` is recorded when an internal transaction tries to +read more rows than cluster setting `sql.defaults.transaction_rows_read_log` +or `sql.defaults.transaction_rows_read_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit_internal` + +An event of type `txn_rows_written_limit_internal` is recorded when an internal transaction tries to +write more rows than cluster setting +`sql.defaults.transaction_rows_written_log` or +`sql.defaults.transaction_rows_written_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL User and Role operations + +Events in this category pertain to SQL statements that modify the +properties of users and roles. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `USER_ADMIN` channel. + + +### `alter_role` + +An event of type `alter_role` is recorded when a role is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | +| `Options` | The options set on the user/role. | no | +| `SetInfo` | Information corresponding to an ALTER ROLE SET statement. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_role` + +An event of type `create_role` is recorded when a role is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the new user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_role` + +An event of type `drop_role` is recorded when a role is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `grant_role` + +An event of type `grant_role` is recorded when a role is granted. + + +| Field | Description | Sensitive | +|--|--|--| +| `GranteeRoles` | The roles being granted to. | yes | +| `Members` | The roles being granted. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `password_hash_converted` + +An event of type `password_hash_converted` is recorded when the password credentials +are automatically converted server-side. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the user/role whose credentials have been converted. | yes | +| `OldMethod` | The previous hash method. | no | +| `NewMethod` | The new hash method. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Sampled SQL Events + +Events in this category report sample of SQL events. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `m_v_c_c_iterator_stats` + +Internal storage iteration statistics for a single execution. + + +| Field | Description | Sensitive | +|--|--|--| +| `StepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `StepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `BlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `BlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `KeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `ValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | + + + +### `sampled_exec_stats` + +An event of type `sampled_exec_stats` contains execution statistics that apply to both statements +and transactions. These stats as a whole are collected using a sampling approach. +These exec stats are meant to contain the same fields as ExecStats in +apps_stats.proto but are for a single execution rather than aggregated executions. +Fields in this struct should be updated in sync with apps_stats.proto. + + +| Field | Description | Sensitive | +|--|--|--| +| `NetworkBytes` | NetworkBytes collects the number of bytes sent over the network by DistSQL components. | no | +| `MaxMemUsage` | MaxMemUsage collects the maximum memory usage that occurred on a node. | no | +| `ContentionTime` | ContentionTime collects the time in seconds statements in the transaction spent contending. | no | +| `NetworkMessages` | NetworkMessages collects the number of messages that were sent over the network by DistSQL components. | no | +| `MaxDiskUsage` | MaxDiskUsage collects the maximum temporary disk usage that occurred. This is set in cases where a query had to spill to disk, e.g. when performing a large sort where not all of the tuples fit in memory. | no | +| `CPUSQLNanos` | CPUSQLNanos collects the CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `MVCCIteratorStats` | Internal storage iteration statistics. | yes | +| `AdmissionWaitTime` | AdmissionWaitTime is the cumulative time spent in admission control queues. | no | + + + +### `sampled_query` + +An event of type `sampled_query` is the SQL query event logged to the telemetry channel. It +contains common SQL event/execution details. + +Note: in version 26.1, these events moved to the `SQL_EXEC` channel. +To test compatability prior to this, set the cluster setting +`log.channel_compatibility_mode.enabled` to true. This will send the +events to `TELEMETRY` instead of `SQL_EXEC`. + + +| Field | Description | Sensitive | +|--|--|--| +| `SkippedQueries` | skipped_queries indicate how many SQL statements were not considered for sampling prior to this one. If the field is omitted, or its value is zero, this indicates that no statement was omitted since the last event. | no | +| `CostEstimate` | Cost of the query as estimated by the optimizer. | no | +| `Distribution` | The distribution of the DistSQL query plan (local, full, or partial). | no | +| `PlanGist` | The query's plan gist bytes as a base64 encoded string. | no | +| `SessionID` | SessionID is the ID of the session that initiated the query. | no | +| `Database` | Name of the database that initiated the query. | no | +| `StatementID` | Statement ID of the query. | no | +| `TransactionID` | Transaction ID of the query. | no | +| `MaxFullScanRowsEstimate` | Maximum number of rows scanned by a full scan, as estimated by the optimizer. | no | +| `TotalScanRowsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer. | no | +| `OutputRowsEstimate` | The number of rows output by the query, as estimated by the optimizer. | no | +| `StatsAvailable` | Whether table statistics were available to the optimizer when planning the query. | no | +| `NanosSinceStatsCollected` | The maximum number of nanoseconds that have passed since stats were collected on any table scanned by this query. | no | +| `BytesRead` | The number of bytes read from disk. | no | +| `RowsRead` | The number of rows read from disk. | no | +| `RowsWritten` | The number of rows written. | no | +| `InnerJoinCount` | The number of inner joins in the query plan. | no | +| `LeftOuterJoinCount` | The number of left (or right) outer joins in the query plan. | no | +| `FullOuterJoinCount` | The number of full outer joins in the query plan. | no | +| `SemiJoinCount` | The number of semi joins in the query plan. | no | +| `AntiJoinCount` | The number of anti joins in the query plan. | no | +| `IntersectAllJoinCount` | The number of intersect all joins in the query plan. | no | +| `ExceptAllJoinCount` | The number of except all joins in the query plan. | no | +| `HashJoinCount` | The number of hash joins in the query plan. | no | +| `CrossJoinCount` | The number of cross joins in the query plan. | no | +| `IndexJoinCount` | The number of index joins in the query plan. | no | +| `LookupJoinCount` | The number of lookup joins in the query plan. | no | +| `MergeJoinCount` | The number of merge joins in the query plan. | no | +| `InvertedJoinCount` | The number of inverted joins in the query plan. | no | +| `ApplyJoinCount` | The number of apply joins in the query plan. | no | +| `ZigZagJoinCount` | The number of zig zag joins in the query plan. | no | +| `ContentionNanos` | The duration of time in nanoseconds that the query experienced contention. | no | +| `Regions` | The regions of the nodes where SQL processors ran. | no | +| `NetworkBytesSent` | The number of network bytes by DistSQL components. | no | +| `MaxMemUsage` | The maximum amount of memory usage by nodes for this query. | no | +| `MaxDiskUsage` | The maximum amount of disk usage by nodes for this query. | no | +| `KVBytesRead` | The number of bytes read at the KV layer for this query. | no | +| `KVPairsRead` | The number of key-value pairs read at the KV layer for this query. | no | +| `KVRowsRead` | The number of rows read at the KV layer for this query. | no | +| `NetworkMessages` | The number of network messages sent by nodes for this query by DistSQL components. | no | +| `IndexRecommendations` | Generated index recommendations for this query. | no | +| `ScanCount` | The number of scans in the query plan. | no | +| `ScanWithStatsCount` | The number of scans using statistics (including forecasted statistics) in the query plan. | no | +| `ScanWithStatsForecastCount` | The number of scans using forecasted statistics in the query plan. | no | +| `TotalScanRowsWithoutForecastsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer without using forecasts. | no | +| `NanosSinceStatsForecasted` | The greatest quantity of nanoseconds that have passed since the forecast time (or until the forecast time, if it is in the future, in which case it will be negative) for any table with forecasted stats scanned by this query. | no | +| `Indexes` | The list of indexes used by this query. | no | +| `CpuTimeNanos` | Collects the cumulative CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `KvGrpcCalls` | The number of grpc calls done to get data form KV nodes | no | +| `KvTimeNanos` | Cumulated time spent waiting for a KV request. This includes disk IO time and potentially network time (if any of the keys are not local). | no | +| `ServiceLatencyNanos` | The time to service the query, from start of parse to end of execute. | no | +| `OverheadLatencyNanos` | The difference between service latency and the sum of parse latency + plan latency + run latency . | no | +| `RunLatencyNanos` | The time to run the query and fetch or compute the result rows. | no | +| `PlanLatencyNanos` | The time to transform the AST into a logical query plan. | no | +| `IdleLatencyNanos` | The time between statement executions in a transaction | no | +| `ParseLatencyNanos` | The time to transform the SQL string into an abstract syntax tree (AST). | no | +| `MvccStepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccStepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccBlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `MvccBlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `MvccKeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `SchemaChangerMode` | SchemaChangerMode is the mode that was used to execute the schema change, if any. | no | +| `SQLInstanceIDs` | SQLInstanceIDs is a list of all the SQL instances used in this statement's execution. | no | +| `KVNodeIDs` | KVNodeIDs is a list of all the KV nodes used in this statement's execution. | no | +| `StatementFingerprintID` | Statement fingerprint ID of the query. | no | +| `UsedFollowerRead` | UsedFollowerRead indicates whether at least some reads were served by the follower replicas. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sampled_transaction` + +An event of type `sampled_transaction` is the event logged to telemetry at the end of transaction execution. + +Note: in version 26.1, these events moved to the `SQL_EXEC` channel. +To test compatability prior to this, set the cluster setting +`log.channel_compatibility_mode.enabled` to true. This will send the +events to `TELEMETRY` instead of `SQL_EXEC`. + + +| Field | Description | Sensitive | +|--|--|--| +| `User` | User is the user account that triggered the transaction. The special usernames `root` and `node` are not considered sensitive. | depends | +| `ApplicationName` | ApplicationName is the application name for the session where the transaction was executed. This is included in the event to ease filtering of logging output by application. | no | +| `TxnCounter` | TxnCounter is the sequence number of the SQL transaction inside its session. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `TransactionID` | TransactionID is the id of the transaction. | no | +| `Committed` | Committed indicates if the transaction committed successfully. We want to include this value even if it is false. | no | +| `ImplicitTxn` | ImplicitTxn indicates if the transaction was an implicit one. We want to include this value even if it is false. | no | +| `StartTimeUnixNanos` | StartTimeUnixNanos is the time the transaction was started. Expressed as unix time in nanoseconds. | no | +| `EndTimeUnixNanos` | EndTimeUnixNanos the time the transaction finished (either committed or aborted). Expressed as unix time in nanoseconds. | no | +| `ServiceLatNanos` | ServiceLatNanos is the time to service the whole transaction, from start to end of execution. | no | +| `SQLSTATE` | SQLSTATE is the SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | ErrorText is the text of the error if any. | partially | +| `NumRetries` | NumRetries is the number of time when the txn was retried automatically by the server. | no | +| `LastAutoRetryReason` | LastAutoRetryReason is a string containing the reason for the last automatic retry. | partially | +| `NumRows` | NumRows is the total number of rows returned across all statements. | no | +| `RetryLatNanos` | RetryLatNanos is the amount of time spent retrying the transaction. | no | +| `CommitLatNanos` | CommitLatNanos is the amount of time spent committing the transaction after all statement operations. | no | +| `IdleLatNanos` | IdleLatNanos is the amount of time spent waiting for the client to send statements while the transaction is open. | no | +| `BytesRead` | BytesRead is the number of bytes read from disk. | no | +| `RowsRead` | RowsRead is the number of rows read from disk. | no | +| `RowsWritten` | RowsWritten is the number of rows written to disk. | no | +| `SampledExecStats` | SampledExecStats is a nested field containing execution statistics. This field will be omitted if the stats were not sampled. | yes | +| `SkippedTransactions` | SkippedTransactions is the number of transactions that were skipped as part of sampling prior to this one. We only count skipped transactions when telemetry logging is enabled and the sampling mode is set to "transaction". | no | +| `TransactionFingerprintID` | TransactionFingerprintID is the fingerprint ID of the transaction. This can be used to find the transaction in the console. | no | +| `StatementFingerprintIDs` | StatementFingerprintIDs is an array of statement fingerprint IDs belonging to this transaction. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Storage telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `level_stats` + +An event of type `level_stats` contains per-level statistics for an LSM. + + +| Field | Description | Sensitive | +|--|--|--| +| `Level` | level is the level ID in a LSM (e.g. level(L0) == 0, etc.) | no | +| `NumFiles` | num_files is the number of files in the level (gauge). | no | +| `SizeBytes` | size_bytes is the size of the level, in bytes (gauge). | no | +| `Score` | score is the compaction score of the level (gauge). | no | +| `BytesIn` | bytes_in is the number of bytes written to this level (counter). | no | +| `BytesIngested` | bytes_ingested is the number of bytes ingested into this level (counter). | no | +| `BytesMoved` | bytes_moved is the number of bytes moved into this level via a move-compaction (counter). | no | +| `BytesRead` | bytes_read is the number of bytes read from this level, during compactions (counter). | no | +| `BytesCompacted` | bytes_compacted is the number of bytes written to this level during compactions (counter). | no | +| `BytesFlushed` | bytes flushed is the number of bytes flushed to this level. This value is always zero for levels other than L0 (counter). | no | +| `TablesCompacted` | tables_compacted is the count of tables compacted into this level (counter). | no | +| `TablesFlushed` | tables_flushed is the count of tables flushed into this level (counter). | no | +| `TablesIngested` | tables_ingested is the count of tables ingested into this level (counter). | no | +| `TablesMoved` | tables_moved is the count of tables moved into this level via move-compactions (counter). | no | +| `NumSublevels` | num_sublevel is the count of sublevels for the level. This value is always zero for levels other than L0 (gauge). | no | + + + +### `store_stats` + +An event of type `store_stats` contains per store stats. + +Note that because stats are scoped to the lifetime of the process, counters +(and certain gauges) will be reset across node restarts. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeId` | node_id is the ID of the node. | no | +| `StoreId` | store_id is the ID of the store. | no | +| `Levels` | levels is a nested message containing per-level statistics. | yes | +| `CacheSize` | cache_size is the size of the cache for the store, in bytes (gauge). | no | +| `CacheCount` | cache_count is the number of items in the cache (gauge). | no | +| `CacheHits` | cache_hits is the number of cache hits (counter). | no | +| `CacheMisses` | cache_misses is the number of cache misses (counter). | no | +| `CompactionCountDefault` | compaction_count_default is the count of default compactions (counter). | no | +| `CompactionCountDeleteOnly` | compaction_count_delete_only is the count of delete-only compactions (counter). | no | +| `CompactionCountElisionOnly` | compaction_count_elision_only is the count of elision-only compactions (counter). | no | +| `CompactionCountMove` | compaction_count_move is the count of move-compactions (counter). | no | +| `CompactionCountRead` | compaction_count_read is the count of read-compactions (counter). | no | +| `CompactionCountRewrite` | compaction_count_rewrite is the count of rewrite-compactions (counter). | no | +| `CompactionNumInProgress` | compactions_num_in_progress is the number of compactions in progress (gauge). | no | +| `CompactionMarkedFiles` | compaction_marked_files is the count of files marked for compaction (gauge). | no | +| `FlushCount` | flush_count is the number of flushes (counter). | no | +| `FlushIngestCount` | | no | +| `FlushIngestTableCount` | | no | +| `FlushIngestTableBytes` | | no | +| `IngestCount` | ingest_count is the number of successful ingest operations (counter). | no | +| `MemtableSize` | memtable_size is the total size allocated to all memtables and (large) batches, in bytes (gauge). | no | +| `MemtableCount` | memtable_count is the count of memtables (gauge). | no | +| `MemtableZombieCount` | memtable_zombie_count is the count of memtables no longer referenced by the current DB state, but still in use by an iterator (gauge). | no | +| `MemtableZombieSize` | memtable_zombie_size is the size, in bytes, of all zombie memtables (gauge). | no | +| `WalLiveCount` | wal_live_count is the count of live WAL files (gauge). | no | +| `WalLiveSize` | wal_live_size is the size, in bytes, of live data in WAL files. With WAL recycling, this value is less than the actual on-disk size of the WAL files (gauge). | no | +| `WalObsoleteCount` | wal_obsolete_count is the count of obsolete WAL files (gauge). | no | +| `WalObsoleteSize` | wal_obsolete_size is the size of obsolete WAL files, in bytes (gauge). | no | +| `WalPhysicalSize` | wal_physical_size is the size, in bytes, of the WAL files on disk (gauge). | no | +| `WalBytesIn` | wal_bytes_in is the number of logical bytes written to the WAL (counter). | no | +| `WalBytesWritten` | wal_bytes_written is the number of bytes written to the WAL (counter). | no | +| `TableObsoleteCount` | table_obsolete_count is the number of tables which are no longer referenced by the current DB state or any open iterators (gauge). | no | +| `TableObsoleteSize` | table_obsolete_size is the size, in bytes, of obsolete tables (gauge). | no | +| `TableZombieCount` | table_zombie_count is the number of tables no longer referenced by the current DB state, but are still in use by an open iterator (gauge). | no | +| `TableZombieSize` | table_zombie_size is the size, in bytes, of zombie tables (gauge). | no | +| `RangeKeySetsCount` | range_key_sets_count is the approximate count of internal range key sets in the store. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## TELEMETRY + +Events in this file are related to bulk ingest operations performance metrics. + +Events in this category are logged to the `TELEMETRY` channel. + + +### `bulk_ingest_completed` + +An event of type `bulk_ingest_completed` is an event that is logged when a bulk ingest job +(restore, import, etc.) completes successfully. +It captures key performance metrics for the operation. + + +| Field | Description | Sensitive | +|--|--|--| +| `JobID` | JobID is the ID of the bulk ingest job. | no | +| `JobType` | JobType identifies the type of bulk ingest job (e.g., "restore", "import"). | no | +| `NumRows` | NumRows is the number of rows successfully ingested. | no | +| `DurationSeconds` | Duration of the ingest operation in seconds. | no | +| `DataSizeMb` | Total logical size of data ingested in megabytes. | no | +| `NodeCount` | Number of nodes that participated in the ingest operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `captured_index_usage_stats` + +An event of type `captured_index_usage_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `TotalReadCount` | TotalReadCount is the number of times the index has been read. | no | +| `LastRead` | LastRead is the timestamp at which the index was last read. | no | +| `TableID` | TableID is the ID of the table on which the index was created. This is same as descpb.TableID and is unique within the cluster. | no | +| `IndexID` | IndexID is the ID of the index within the scope of the given table. | no | +| `DatabaseName` | DatabaseName is the name of the database in which the index was created. | no | +| `TableName` | TableName is the name of the table on which the index was created. | no | +| `IndexName` | IndexName is the name of the index within the scope of the given table. | no | +| `IndexType` | IndexType is the type of the index. Index types include "primary" and "secondary". | no | +| `IsUnique` | IsUnique indicates if the index has a UNIQUE constraint. | no | +| `IsInverted` | IsInverted indicates if the index is an inverted index. | no | +| `CreatedAt` | CreatedAt is the timestamp at which the index was created. | no | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `recovery_event` + +An event of type `recovery_event` is an event that is logged on every invocation of BACKUP, +RESTORE, and on every BACKUP schedule creation, with the appropriate subset +of fields populated depending on the type of event. This event is is also +logged whenever a BACKUP and RESTORE job completes or fails. + + +| Field | Description | Sensitive | +|--|--|--| +| `RecoveryType` | RecoveryType is the type of recovery described by this event, which is one of - backup - scheduled_backup - create_schedule - restore

It can also be a job event corresponding to the recovery, which is one of - backup_job - scheduled_backup_job - restore_job | no | +| `TargetScope` | TargetScope is the largest scope of the targets that the user is backing up or restoring based on the following order: table < schema < database < full cluster. | no | +| `IsMultiregionTarget` | IsMultiregionTarget is true if any of the targets contain objects with multi-region primitives. | no | +| `TargetCount` | TargetCount is the number of targets the in the BACKUP/RESTORE. | no | +| `DestinationStorageTypes` | DestinationStorageTypes are the types of storage that the user is backing up to or restoring from. | no | +| `DestinationAuthTypes` | DestinationAuthTypes are the types of authentication methods that the user is using to access the destination storage. | no | +| `IsLocalityAware` | IsLocalityAware indicates if the BACKUP or RESTORE is locality aware. | no | +| `WithRevisionHistory` | WithRevisionHistory is true if the BACKUP includes revision history. | no | +| `HasEncryptionPassphrase` | HasEncryptionPassphrase is true if the user provided an encryption passphrase to encrypt/decrypt their backup. | no | +| `KMSType` | KMSType is the type of KMS the user is using to encrypt/decrypt their backup. | no | +| `KMSCount` | KMSCount is the number of KMS the user is using. | no | +| `Options` | Options contain all the names of the options specified by the user in the BACKUP or RESTORE statement. For options that are accompanied by a value, only those with non-empty values will be present.

It's important to note that there are no option values anywhere in the event payload. Future changes to telemetry should refrain from adding values to the payload unless they are properly redacted. | no | +| `JobID` | JobID is the ID of the BACKUP/RESTORE job. | no | +| `ResultStatus` | ResultStatus indicates whether the job succeeded or failed. | no | +| `ErrorText` | ErrorText is the text of the error that caused the job to fail. | partially | +| `RecurringCron` | RecurringCron is the crontab for the incremental backup. | no | +| `FullBackupCron` | FullBackupCron is the crontab for the full backup. | no | +| `CustomFirstRunTime` | CustomFirstRunTime is the timestamp for the user configured first run time. Expressed as nanoseconds since the Unix epoch. | no | +| `IgnoreExistingBackup` | IgnoreExistingBackup is true iff the BACKUP schedule should still be created even if a backup is already present in its destination. | no | +| `ApplicationName` | The application name for the session where recovery event was created. | no | +| `NumRows` | NumRows is the number of rows successfully imported, backed up or restored. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_descriptor` + +An event of type `schema_descriptor` is an event for schema telemetry, whose purpose is +to take periodic snapshots of the cluster's SQL schema and publish them in +the telemetry log channel. For all intents and purposes, the data in such a +snapshot can be thought of the outer join of certain system tables: +namespace, descriptor, and at some point perhaps zones, etc. + +Snapshots are too large to conveniently be published as a single log event, +so instead they're broken down into SchemaDescriptor events which +contain the data in one record of this outer join projection. These events +are prefixed by a header (a SchemaSnapshotMetadata event). + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of the snapshot that this event is part of. | no | +| `ParentDatabaseID` | ParentDatabaseID matches the same key column in system.namespace. | no | +| `ParentSchemaID` | ParentSchemaID matches the same key column in system.namespace. | no | +| `Name` | Name matches the same key column in system.namespace. | no | +| `DescID` | DescID matches the 'id' column in system.namespace and system.descriptor. | no | +| `Desc` | Desc matches the 'descriptor' column in system.descriptor. Some contents of the descriptor may be redacted to prevent leaking PII. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_snapshot_metadata` + +An event of type `schema_snapshot_metadata` is an event describing a schema snapshot, which +is a set of SchemaDescriptor messages sharing the same SnapshotID. + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of this snapshot. | no | +| `NumRecords` | NumRecords is how many SchemaDescriptor events are in the snapshot. | no | +| `AsOfTimestamp` | AsOfTimestamp is when the snapshot was taken. This is equivalent to the timestamp given in the AS OF SYSTEM TIME clause when querying the namespace and descriptor tables in the system database. Expressed as nanoseconds since the Unix epoch. | no | +| `Errors` | Errors records any errors encountered when post-processing this snapshot, which includes the redaction of any potential PII. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Zone config events + +Events in this category pertain to zone configuration changes on +the SQL schema or system ranges. + +When zone configs apply to individual tables or other objects in a +SQL logical schema, they are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these zone config events are preserved +in each tenant's own `system.eventlog` table. + +When they apply to cluster-level ranges (e.g., the system zone config), +they are stored in the system tenant's own `system.eventlog` table. + +Events in this category are logged to the `OPS` channel. + + +### `remove_zone_config` + +An event of type `remove_zone_config` is recorded when a zone config is removed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `set_zone_config` + +An event of type `set_zone_config` is recorded when a zone config is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `ResolvedOldConfig` | The string representation of the resolved old zone config. This is not necessarily the same as the zone config that was previously set -- as it includes the resolved values of the zone config options. In other words, a zone config that hasn't been properly "set" yet (and inherits from its parent) will have a resolved_old_config that has details of the values it inherits from its parent. This is particularly useful to get a proper diff between the old and new zone config. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + + + + +## Enumeration types + +### `AuthFailReason` + +AuthFailReason is the inventory of possible reasons for an +authentication failure. + + +| Value | Textual alias in code or documentation | Description | +|--|--|--| +| 0 | UNKNOWN | is reported when the reason is unknown. | +| 1 | USER_RETRIEVAL_ERROR | occurs when there was an internal error accessing the principals. | +| 2 | USER_NOT_FOUND | occurs when the principal is unknown. | +| 3 | LOGIN_DISABLED | occurs when the user does not have LOGIN privileges. | +| 4 | METHOD_NOT_FOUND | occurs when no HBA rule matches or the method does not exist. | +| 5 | PRE_HOOK_ERROR | occurs when the authentication handshake encountered a protocol error. | +| 6 | CREDENTIALS_INVALID | occurs when the client-provided credentials were invalid. | +| 7 | CREDENTIALS_EXPIRED | occur when the credentials provided by the client are expired. | +| 8 | NO_REPLICATION_ROLEOPTION | occurs when the connection requires a replication role option, but the user does not have it. | +| 9 | AUTHORIZATION_ERROR | is used for errors during the authorization phase. For example, this would include issues with mapping LDAP groups to SQL roles and granting those roles to the user. | +| 10 | PROVISIONING_ERROR | is used for errors during the user provisioning phase. This would include errors when the transaction to provision the authenticating user failed to execute. | + + + diff --git a/src/current/_includes/cockroach-generated/release-26.1/logformats.md b/src/current/_includes/cockroach-generated/release-26.1/logformats.md new file mode 100644 index 00000000000..89580c9fc15 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-26.1/logformats.md @@ -0,0 +1,382 @@ + +The supported log output formats are documented below. + + +- [`crdb-v1`](#format-crdb-v1) + +- [`crdb-v1-count`](#format-crdb-v1-count) + +- [`crdb-v1-tty`](#format-crdb-v1-tty) + +- [`crdb-v1-tty-count`](#format-crdb-v1-tty-count) + +- [`crdb-v2`](#format-crdb-v2) + +- [`crdb-v2-tty`](#format-crdb-v2-tty) + +- [`json`](#format-json) + +- [`json-compact`](#format-json-compact) + +- [`json-fluent`](#format-json-fluent) + +- [`json-fluent-compact`](#format-json-fluent-compact) + + + +## Format `crdb-v1` + + +This is a legacy file format used from CockroachDB v1.0. + +Each log entry is emitted using a common prefix, described below, followed by: + +- The logging context tags enclosed between `[` and `]`, if any. It is possible + for this to be omitted if there were no context tags. +- Optionally, a counter column, if the option 'show-counter' is enabled. See below for details. +- the text of the log entry. + +Beware that the text of the log entry can span multiple lines. +The following caveats apply: + +- The text of the log entry can start with text enclosed between `[` and `]`. + If there were no logging tags to start with, it is not possible to distinguish between + logging context tag information and a `[...]` string in the main text of the + log entry. This means that this format is ambiguous. + + To remove this ambiguity, you can use the option 'show-counter'. + +- The text of the log entry can embed arbitrary application-level strings, + including strings that represent log entries. In particular, an accident + of implementation can cause the common entry prefix (described below) + to also appear on a line of its own, as part of the payload of a previous + log entry. There is no automated way to recognize when this occurs. + Care must be taken by a human observer to recognize these situations. + +- The log entry parser provided by CockroachDB to read log files is faulty + and is unable to recognize the aforementioned pitfall; nor can it read + entries larger than 64KiB successfully. Generally, use of this internal + log entry parser is discouraged for entries written with this format. + +See the newer format `crdb-v2` for an alternative +without these limitations. + +### Header lines + +At the beginning of each file, a header is printed using a similar format as +regular log entries. This header reports when the file was created, +which parameters were used to start the server, the server identifiers +if known, and other metadata about the running process. + +- This header appears to be logged at severity `INFO` (with an `I` prefix + at the start of the line) even though it does not really have a severity. +- The header is printed unconditionally even when a filter is configured to + omit entries at the `INFO` level. + +### Common log entry prefix + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker tags counter + +Reminder, the tags may be omitted; and the counter is only printed if the option +'show-counter' is specified. + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (omitted if zero for use by tests). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. | +| line | The line number where the entry originated. | +| marker | Redactability marker ` + redactableIndicator + ` (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. May be absent. | +| counter | The entry counter. Only included if 'show-counter' is enabled. | + +The redactability marker can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. + +If the marker ` + redactableIndicator + ` is present, the remainder of the log entry +contains delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `show-counter` | Whether to include the counter column in the line header. Without it, the format may be ambiguous due to the optionality of tags. | +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v1-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: none` + + +## Format `crdb-v1-tty` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: false` +- `colors: auto` + + +## Format `crdb-v1-tty-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: auto` + + +## Format `crdb-v2` + +This is the main file format used from CockroachDB v21.1. + +Each log entry is emitted using a common prefix, described below, +followed by the text of the log entry. + +### Entry format + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker [tags...] counter cont + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (zero when cannot be determined). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. Also see below. | +| line | The line number where the entry originated. | +| marker | Redactability marker "⋮" (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. See below. | +| counter | The optional entry counter (see below for details). | +| cont | Continuation mark for structured and multi-line entries. See below. | + +The `chan@` prefix before the file name indicates the logging channel, +and is omitted if the channel is `DEV`. + +The file name may be prefixed by the string `(gostd) ` to indicate +that the log entry was produced inside the Go standard library, instead +of a CockroachDB component. Entry parsers must be configured to ignore this prefix +when present. + +`marker` can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. +If the marker "⋮" is present, the remainder of the log entry +contains delimiters (‹...›) +around fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +when log redaction is requested. + +The logging `tags` are enclosed between square brackets `[...]`, +and the syntax `[-]` is used when there are no logging tags +associated with the log entry. + +`counter` is numeric, and is incremented for every +log entry emitted to this sink. (There is thus one counter sequence per +sink.) For entries that do not have a counter value +associated (e.g., header entries in file sinks), the counter position +in the common prefix is empty: `tags` is then +followed by two ASCII space characters, instead of one space; the `counter`, +and another space. The presence of the two ASCII spaces indicates +reliably that no counter was present. + +`cont` is a format/continuation indicator: + +| Continuation indicator | ASCII | Description | +|------------------------|-------|--| +| space | 0x32 | Start of an unstructured entry. | +| equal sign, "=" | 0x3d | Start of a structured entry. | +| exclamation mark, "!" | 0x21 | Start of an embedded stack trace. | +| plus sign, "+" | 0x2b | Continuation of a multi-line entry. The payload contains a newline character at this position. | +| vertical bar | 0x7c | Continuation of a large entry. | + +### Examples + +Example single-line unstructured entry: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 started with engine type ‹2› +~~~ + +Example multi-line unstructured entry: + +~~~ +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 node startup completed: +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 +CockroachDB node starting at 2021-01-16 21:49 (took 0.0s) +~~~ + +Example structured entry: + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventType":"node_restart"} +~~~ + +Example long entries broken up into multiple lines: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.... +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 |aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +~~~ + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventTy... +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 |pe":"node_restart"} +~~~ + +### Backward-compatibility notes + +Entries in this format can be read by most `crdb-v1` log parsers, +in particular the one included in the DB console and +also the [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +facility. + +However, implementers of previous version parsers must +understand that the logging tags field is now always +included, and the lack of logging tags is included +by a tag string set to `[-]`. + +Likewise, the entry counter is now also always included, +and there is a special character after `counter` +to indicate whether the remainder of the line is a +structured entry, or a continuation of a previous entry. + +Finally, in the previous format, structured entries +were prefixed with the string `Structured entry: `. In +the new format, they are prefixed by the `=` continuation +indicator. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v2-tty` + +This format name is an alias for 'crdb-v2' with +the following format option defaults: + +- `colors: auto` + + +## Format `json` + +This format emits log entries as a JSON payload. + +The JSON object is guaranteed to not contain unescaped newlines +or other special characters, and the entry as a whole is followed +by a newline character. This makes the format suitable for +processing over a stream unambiguously. + +Each entry contains at least the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `tag` | `tag` | (Only if the option `fluent-tag: true` is given.) A Fluent tag for the event, formed by the process name and the logging channel. | +| `d` | `datetime` | The pretty-printed date/time of the event timestamp, if enabled via options. | +| `f` | `file` | The name of the source file where the event was emitted. | +| `g` | `goroutine` | The identifier of the goroutine where the event was emitted. | +| `l` | `line` | The line number where the event was emitted in the source. | +| `r` | `redactable` | Whether the payload is redactable (see below for details). | +| `t` | `timestamp` | The timestamp at which the event was emitted on the logging channel. | +| `v` | `version` | The binary version with which the event was generated. | + + +After a couple of *header* entries written at the beginning of each log sink, +all subsequent log entries also contain the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `C` | `channel` | The name of the logging channel where the event was sent. | +| `sev` | `severity` | The severity of the event. | +| `c` | `channel_numeric` | The numeric identifier for the logging channel where the event was sent. | +| `n` | `entry_counter` | The entry number on this logging sink, relative to the last process restart. | +| `s` | `severity_numeric` | The numeric value of the severity of the event. | + + +Additionally, the following fields are conditionally present: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `N` | `node_id` | The node ID where the event was generated, once known. Only reported for single-tenant or KV servers. | +| `x` | `cluster_id` | The cluster ID where the event was generated, once known. Only reported for single-tenant of KV servers. | +| `q` | `instance_id` | The SQL instance ID where the event was generated, once known. | +| `T` | `tenant_id` | The SQL tenant ID where the event was generated, once known. | +| `V` | `tenant_name` | The SQL virtual cluster where the event was generated, once known. | +| `tags` | `tags` | The logging context tags for the entry, if there were context tags. | +| `message` | `message` | For unstructured events, the flat text payload. | +| `event` | `event` | The logging event, if structured (see below for details). | +| `stacks` | `stacks` | Goroutine stacks, for fatal events. | + +When an entry is structured, the `event` field maps to a dictionary +whose structure is one of the documented structured events. See the [reference documentation](eventlog.html) +for structured events for a list of possible payloads. + +When the entry is marked as `redactable`, the `tags`, `message`, and/or `event` payloads +contain delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `datetime-format` | The format to use for the `datetime` field. The value can be one of `none`, `iso8601`/`rfc3339` (synonyms), or `rfc1123`. Default is `none`. | +| `datetime-timezone` | The timezone to use for the `datetime` field. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | +| `tag-style` | The tags to include in the envelope. The value can be `compact` (one letter tags) or `verbose` (long-form tags). Default is `verbose`. | +| `fluent-tag` | Whether to produce an additional field called `tag` for Fluent compatibility. Default is `false`. | + + + +## Format `json-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: false` +- `tag-style: compact` + + +## Format `json-fluent` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: verbose` + + +## Format `json-fluent-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: compact` + + diff --git a/src/current/_includes/cockroach-generated/release-26.1/logging.md b/src/current/_includes/cockroach-generated/release-26.1/logging.md new file mode 100644 index 00000000000..7661187987e --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-26.1/logging.md @@ -0,0 +1,188 @@ +## Logging levels (severities) + +### INFO + +The `INFO` severity is used for informational messages that do not +require action. + +### WARNING + +The `WARNING` severity is used for situations which may require special handling, +where normal operation is expected to resume automatically. + +### ERROR + +The `ERROR` severity is used for situations that require special handling, +where normal operation could not proceed as expected. +Other operations can continue mostly unaffected. + +### FATAL + +The `FATAL` severity is used for situations that require an immedate, hard +server shutdown. A report is also sent to telemetry if telemetry +is enabled. + + +## Logging channels + +### `DEV` + +The `DEV` channel is used during development to collect log +details useful for troubleshooting that fall outside the +scope of other channels. It is also the default logging +channel for events not associated with a channel. + +This channel is special in that there are no constraints as to +what may or may not be logged on it. Conversely, users in +production deployments are invited to not collect `DEV` logs in +centralized logging facilities, because they likely contain +sensitive operational data. +See [Configure logs](configure-logs.html#dev-channel). + +### `OPS` + +The `OPS` channel is used to report "point" operational events, +initiated by user operators or automation: + + - Operator or system actions on server processes: process starts, + stops, shutdowns, crashes (if they can be logged), + including each time: command-line parameters, current version being run + - Actions that impact the topology of a cluster: node additions, + removals, decommissions, etc. + - Job-related initiation or termination + - [Cluster setting](cluster-settings.html) changes + - [Zone configuration](configure-replication-zones.html) changes + +### `HEALTH` + +The `HEALTH` channel is used to report "background" operational +events, initiated by CockroachDB or reporting on automatic processes: + + - Current resource usage, including critical resource usage + - Node-node connection events, including connection errors and + gossip details + - Range and table leasing events + - Up- and down-replication, range unavailability + +### `STORAGE` + +The `STORAGE` channel is used to report low-level storage +layer events (RocksDB/Pebble). + +### `SESSIONS` + +The `SESSIONS` channel is used to report client network activity when enabled via +the `server.auth_log.sql_connections.enabled` and/or +`server.auth_log.sql_sessions.enabled` [cluster setting](cluster-settings.html): + + - Connections opened/closed + - Authentication events: logins, failed attempts + - Session and query cancellation + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_SCHEMA` + +The `SQL_SCHEMA` channel is used to report changes to the +SQL logical schema, excluding privilege and ownership changes +(which are reported separately on the `PRIVILEGES` channel) and +zone configuration changes (which go to the `OPS` channel). + +This includes: + + - Database/schema/table/sequence/view/type creation + - Adding/removing/changing table columns + - Changing sequence parameters + +`SQL_SCHEMA` events generally comprise changes to the schema that affect the +functional behavior of client apps using stored objects. + +### `USER_ADMIN` + +The `USER_ADMIN` channel is used to report changes +in users and roles, including: + + - Users added/dropped + - Changes to authentication credentials (e.g., passwords, validity, etc.) + - Role grants/revocations + - Role option grants/revocations + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `PRIVILEGES` + +The `PRIVILEGES` channel is used to report data +authorization changes, including: + + - Privilege grants/revocations on database, objects, etc. + - Object ownership changes + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SENSITIVE_ACCESS` + +The `SENSITIVE_ACCESS` channel is used to report SQL +data access to sensitive data: + + - Data access audit events (when table audit is enabled via + [ALTER TABLE ... EXPERIMENTAL_AUDIT](alter-table.html#experimental_audit)) + - Data access audit events (when role-based audit is enabled via + [`sql.log.user_audit` cluster setting](role-based-audit-logging.html#syntax-of-audit-settings)) + - SQL statements executed by users with the admin role + - Operations that write to system tables + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_EXEC` + +The `SQL_EXEC` channel is used to report SQL execution on +behalf of client connections: + + - Logical SQL statement executions (when enabled via the + `sql.log.all_statements.enabled` [cluster setting](cluster-settings.html)) + - uncaught Go panic errors during the execution of a SQL statement. + +### `SQL_PERF` + +The `SQL_PERF` channel is used to report SQL executions +that are marked as "out of the ordinary" +to facilitate performance investigations. +This includes the SQL "slow query log". + +Arguably, this channel overlaps with `SQL_EXEC`. +However, we keep both channels separate for backward compatibility +with versions prior to v21.1, where the corresponding events +were redirected to separate files. + +### `SQL_INTERNAL_PERF` + +The `SQL_INTERNAL_PERF` channel is like the `SQL_PERF` channel, but is aimed at +helping developers of CockroachDB itself. It exists as a separate +channel so as to not pollute the `SQL_PERF` logging output with +internal troubleshooting details. + +### `TELEMETRY` + +The `TELEMETRY` channel reports telemetry events. Telemetry events describe +feature usage within CockroachDB and anonymizes any application- +specific data. + +### `KV_DISTRIBUTION` + +The `KV_DISTRIBUTION` channel is used to report data distribution events, such as moving +replicas between stores in the cluster, or adding (removing) replicas to +ranges. + +### `CHANGEFEED` + +The `CHANGEFEED` channel is used to report changefeed events + +### `KV_EXEC` + +The `KV_EXEC` channel is used to report KV execution events that don't fall into the +KV_DISTRIBUTION channel. + diff --git a/src/current/_includes/cockroach-generated/release-26.1/settings/settings.html b/src/current/_includes/cockroach-generated/release-26.1/settings/settings.html new file mode 100644 index 00000000000..a08f0e0ad85 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-26.1/settings/settings.html @@ -0,0 +1,396 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingTypeDefaultDescriptionSupported Deployments
admission.disk_bandwidth_tokens.elastic.enabled
booleantruewhen true, and provisioned bandwidth for the disk corresponding to a store is configured, tokens for elastic work will be limited if disk bandwidth becomes a bottleneckAdvanced/Self-Hosted
admission.epoch_lifo.enabled
booleanfalsewhen true, epoch-LIFO behavior is enabled when there is significant delay in admissionBasic/Standard/Advanced/Self-Hosted
admission.epoch_lifo.epoch_closing_delta_duration
duration5msthe delta duration before closing an epoch, for epoch-LIFO admission control orderingBasic/Standard/Advanced/Self-Hosted
admission.epoch_lifo.epoch_duration
duration100msthe duration of an epoch, for epoch-LIFO admission control orderingBasic/Standard/Advanced/Self-Hosted
admission.epoch_lifo.queue_delay_threshold_to_switch_to_lifo
duration105msthe queue delay encountered by a (tenant,priority) for switching to epoch-LIFO orderingBasic/Standard/Advanced/Self-Hosted
admission.kv.enabled
booleantruewhen true, work performed by the KV layer is subject to admission controlAdvanced/Self-Hosted
admission.sql_kv_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a KV response is subject to admission controlBasic/Standard/Advanced/Self-Hosted
admission.sql_sql_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a DistSQL response is subject to admission controlBasic/Standard/Advanced/Self-Hosted
bulkio.backup.file_size
byte size128 MiBtarget size for individual data files produced during BACKUPBasic/Standard/Advanced/Self-Hosted
bulkio.backup.read_timeout
duration5m0samount of time after which a read attempt is considered timed out, which causes the backup to failBasic/Standard/Advanced/Self-Hosted
bulkio.backup.read_with_priority_after
duration1m0samount of time since the read-as-of time above which a BACKUP should use priority when retrying readsBasic/Standard/Advanced/Self-Hosted
physical_replication.consumer.minimum_flush_interval
(alias: bulkio.stream_ingestion.minimum_flush_interval)
duration5sthe minimum timestamp between flushes; flushes may still occur if internal buffers fill upAdvanced/Self-Hosted
changefeed.aggregator.flush_jitter
float0.1jitter aggregator flushes as a fraction of min_checkpoint_frequency. This setting has no effect if min_checkpoint_frequency is set to 0.Basic/Standard/Advanced/Self-Hosted
changefeed.backfill.concurrent_scan_requests
integer0number of concurrent scan requests per node issued during a backfillBasic/Standard/Advanced/Self-Hosted
changefeed.backfill.scan_request_size
integer524288the maximum number of bytes returned by each scan requestBasic/Standard/Advanced/Self-Hosted
changefeed.batch_reduction_retry.enabled
(alias: changefeed.batch_reduction_retry_enabled)
booleanfalseif true, kafka changefeeds upon erroring on an oversized batch will attempt to resend the messages with progressively lower batch sizesBasic/Standard/Advanced/Self-Hosted
changefeed.default_range_distribution_strategy
enumerationdefaultcontrols how changefeed work is distributed across nodes. 'default' defers to DistSQL for node selection and work distribution. 'balanced_simple' uses DistSQL for node selection but then attempts to evenly distribute ranges across those selected nodes for better load balancing. this setting does not override locality restrictions and can be overridden per-changefeed using the 'range_distribution_strategy' option. [default = 0, balanced_simple = 1]Basic/Standard/Advanced/Self-Hosted
changefeed.event_consumer_worker_queue_size
integer16if changefeed.event_consumer_workers is enabled, this setting sets the maxmimum number of events which a worker can bufferBasic/Standard/Advanced/Self-Hosted
changefeed.event_consumer_workers
integer0the number of workers to use when processing events: <0 disables, 0 assigns a reasonable default, >0 assigns the setting value. for experimental/core changefeeds and changefeeds using parquet format, this is disabledBasic/Standard/Advanced/Self-Hosted
changefeed.fast_gzip.enabled
booleantrueuse fast gzip implementationBasic/Standard/Advanced/Self-Hosted
changefeed.span_checkpoint.lag_threshold
(alias: changefeed.frontier_highwater_lag_checkpoint_threshold)
duration10m0sthe amount of time a changefeed's lagging (slowest) spans must lag behind its leading (fastest) spans before a span-level checkpoint to save leading span progress is written; if 0, span-level checkpoints due to lagging spans is disabledBasic/Standard/Advanced/Self-Hosted
changefeed.kafka.max_request_size
byte size256 MiBthe maximum number of uncompressed bytes sent in a single request to a Kafka broker; lowering this value helps avoid spurious "message too large" errors that can occur when multiple messages are combined into a single batch; this setting is overridden by the per-changefeed Flush { MaxBytes: <int> } optionBasic/Standard/Advanced/Self-Hosted
changefeed.kafka_v2_error_details.enabled
booleantrueif enabled, Kafka v2 sinks will include the message key, size, and MVCC timestamp in message too large errorsBasic/Standard/Advanced/Self-Hosted
changefeed.memory.per_changefeed_limit
byte size512 MiBcontrols amount of data that can be buffered per changefeedBasic/Standard/Advanced/Self-Hosted
changefeed.resolved_timestamp.min_update_interval
(alias: changefeed.min_highwater_advance)
duration0sminimum amount of time that must have elapsed since the last time a changefeed's resolved timestamp was updated before it is eligible to be updated again; default of 0 means no minimum interval is enforced but updating will still be limited by the average time it takes to checkpoint progressBasic/Standard/Advanced/Self-Hosted
changefeed.node_throttle_config
stringspecifies node level throttling configuration for all changefeeedsBasic/Standard/Advanced/Self-Hosted
changefeed.partition_alg.enabled
booleanfalseif enabled, allows specifying the partition_alg changefeed option to choose between fnv-1a (default) and murmur2 hash functions for Kafka partitioning. Only affects changefeeds using a kafka sink with changefeed.new_kafka_sink_enabled set to true.Basic/Standard/Advanced/Self-Hosted
changefeed.progress.frontier_persistence.interval
duration30sminimum amount of time that must elapse before a changefeed will persist its entire span frontier againBasic/Standard/Advanced/Self-Hosted
changefeed.protect_timestamp.max_age
duration96h0m0sfail the changefeed if the protected timestamp age exceeds this threshold; 0 disables expirationBasic/Standard/Advanced/Self-Hosted
changefeed.protect_timestamp_interval
duration10m0scontrols how often the changefeed forwards its protected timestamp to the resolved timestampBasic/Standard/Advanced/Self-Hosted
changefeed.schema_feed.read_with_priority_after
duration1m0sretry with high priority if we were not able to read descriptors for too long; 0 disablesBasic/Standard/Advanced/Self-Hosted
changefeed.sink_io_workers
integer0the number of workers used by changefeeds when sending requests to the sink (currently the batching versions of webhook, pubsub, and kafka sinks that are enabled by changefeed.new_<sink type>_sink_enabled only): <0 disables, 0 assigns a reasonable default, >0 assigns the setting valueBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.concurrent_upload_buffers
integer1controls the number of concurrent buffers that will be used by the Azure client when uploading chunks.Each buffer can buffer up to cloudstorage.write_chunk.size of memory during an uploadBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.gs.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.gs.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.gs.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.gs.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.custom_ca
stringcustom root CA (appended to system's default CAs) for verifying certificates when interacting with HTTPS storageBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nodelocal.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nodelocal.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nodelocal.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nodelocal.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nullsink.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nullsink.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nullsink.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nullsink.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.s3.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.s3.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.s3.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.s3.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.timeout
duration10m0sthe timeout for import/export storage operationsBasic/Standard/Advanced/Self-Hosted
cloudstorage.userfile.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.userfile.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.userfile.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.userfile.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cluster.auto_upgrade.enabled
booleantruedisable automatic cluster version upgrade until resetBasic/Standard/Advanced/Self-Hosted
cluster.organization
stringorganization nameAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
cluster.preserve_downgrade_option
stringdisable (automatic or manual) cluster version upgrade from the specified version until resetBasic/Standard/Advanced/Self-Hosted
debug.zip.redact_addresses.enabled
booleanfalseenables the redaction of hostnames and ip addresses in debug zipBasic/Standard/Advanced/Self-Hosted
diagnostics.active_query_dumps.enabled
booleantrueexperimental: enable dumping of anonymized active queries to disk when node is under memory pressureAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
diagnostics.forced_sql_stat_reset.interval
duration2h0m0sinterval after which the reported SQL Stats are reset even if not collected by telemetry reporter. It has a max value of 24H.Basic/Standard/Advanced/Self-Hosted
diagnostics.memory_monitoring_dumps.enabled
booleantrueenable dumping of memory monitoring state at the same time as heap profiles are takenAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
diagnostics.reporting.enabled
booleantrueenable reporting diagnostic metrics to cockroach labs, but is ignored for Trial or Free licensesBasic/Standard/Advanced/Self-Hosted
diagnostics.reporting.interval
duration1h0m0sinterval at which diagnostics data should be reportedBasic/Standard/Advanced/Self-Hosted
enterprise.license
stringthe encoded cluster licenseAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
external.graphite.endpoint
stringif nonempty, push server metrics to the Graphite or Carbon server at the specified host:portBasic/Standard/Advanced/Self-Hosted
external.graphite.interval
duration10sthe interval at which metrics are pushed to Graphite (if enabled)Basic/Standard/Advanced/Self-Hosted
feature.backup.enabled
booleantrueset to true to enable backups, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.changefeed.enabled
booleantrueset to true to enable changefeeds, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.export.enabled
booleantrueset to true to enable exports, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.import.enabled
booleantrueset to true to enable imports, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.infer_rbr_region_col_using_constraint.enabled
booleanfalseset to true to enable looking up the region column via a foreign key constraint in a REGIONAL BY ROW table, false to disable; default is falseBasic/Standard/Advanced/Self-Hosted
feature.restore.enabled
booleantrueset to true to enable restore, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.schema_change.enabled
booleantrueset to true to enable schema changes, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.stats.enabled
booleantrueset to true to enable CREATE STATISTICS/ANALYZE, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.vector_index.enabled
booleantrueset to true to enable vector indexes, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
jobs.retention_time
duration336h0m0sthe amount of time for which records for completed jobs are retainedBasic/Standard/Advanced/Self-Hosted
kv.allocator.lease_rebalance_threshold
float0.05minimum fraction away from the mean a store's lease count can be before it is considered for lease-transfersAdvanced/Self-Hosted
kv.allocator.load_based_lease_rebalancing.enabled
booleantrueset to enable rebalancing of range leases based on load and latencyAdvanced/Self-Hosted
kv.allocator.load_based_rebalancing
enumerationleases and replicaswhether to rebalance based on the distribution of load across stores [off = 0, leases = 1, leases and replicas = 2, multi-metric only = 3, multi-metric and count = 4]Advanced/Self-Hosted
kv.allocator.load_based_rebalancing.objective
enumerationcpuwhat objective does the cluster use to rebalance; if set to `qps` the cluster will attempt to balance qps among stores, if set to `cpu` the cluster will attempt to balance cpu usage among stores [qps = 0, cpu = 1]Advanced/Self-Hosted
kv.allocator.load_based_rebalancing_interval
duration1m0sthe rough interval at which each store will check for load-based lease / replica rebalancing opportunitiesAdvanced/Self-Hosted
kv.allocator.qps_rebalance_threshold
float0.1minimum fraction away from the mean a store's QPS (such as queries per second) can be before it is considered overfull or underfullAdvanced/Self-Hosted
kv.allocator.range_rebalance_threshold
float0.05minimum fraction away from the mean a store's range count can be before it is considered overfull or underfullAdvanced/Self-Hosted
kv.allocator.store_cpu_rebalance_threshold
float0.1minimum fraction away from the mean a store's cpu usage can be before it is considered overfull or underfullAdvanced/Self-Hosted
kv.bulk_io_write.max_rate
byte size1.0 TiBthe rate limit (bytes/sec) to use for writes to disk on behalf of bulk io opsAdvanced/Self-Hosted
kv.bulk_io_write.min_capacity_remaining_fraction
float0.05remaining store capacity fraction below which bulk ingestion requests are rejectedAdvanced/Self-Hosted
kv.bulk_sst.max_allowed_overage
byte size64 MiBif positive, allowed size in excess of target size for SSTs from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryAdvanced/Self-Hosted
kv.bulk_sst.target_size
byte size16 MiBtarget size for SSTs emitted from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.follower_reads.enabled
(alias: kv.closed_timestamp.follower_reads_enabled)
booleantrueallow (all) replicas to serve consistent historical reads based on closed timestamp informationAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.lead_for_global_reads_auto_tune.enabled
booleanfalseif enabled, observed network latency between leaseholders and their furthest follower will be used to adjust closed timestamp policies for rangesranges configured to serve global reads. kv.closed_timestamp.lead_for_global_reads_override takes precedence if set.Advanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.lead_for_global_reads_override
duration0sif nonzero, overrides the lead time that global_read ranges use to publish closed timestampsAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.side_transport_interval
duration200msthe interval at which the closed timestamp side-transport attempts to advance each range's closed timestamp; set to 0 to disable the side-transportAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.side_transport_pacing_refresh_interval
duration10msthe refresh interval for the task pacer that controls pacing of sending sidetransport updates to avoid overloading the system when many connections are waitingAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.side_transport_pacing_smear_interval
duration1msthe smear interval for the task pacer that controls the amount of time each paced batch is going to take when broadcasting sidetransport updatesAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.target_duration
duration3sif nonzero, attempt to provide closed timestamp notifications for timestamps trailing cluster time by approximately this durationAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.dist_sender.circuit_breaker.cancellation.enabled
booleantruewhen enabled, in-flight requests will be cancelled when the circuit breaker tripsBasic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breaker.cancellation.write_grace_period
duration10show long after the circuit breaker trips to cancel write requests (these can't retry internally, so should be long enough to allow quorum/lease recovery)Basic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breaker.probe.interval
duration3sinterval between replica probesBasic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breaker.probe.threshold
duration3sduration of errors or stalls after which a replica will be probedBasic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breaker.probe.timeout
duration3stimeout for replica probesBasic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breakers.mode
enumerationliveness range onlyset of ranges to trip circuit breakers for failing or stalled replicas [no ranges = 0, liveness range only = 1, all ranges = 2]Basic/Standard/Advanced/Self-Hosted
kv.lease_transfer_read_summary.global_budget
byte size0 Bcontrols the maximum number of bytes that will be used to summarize the global segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Advanced/Self-Hosted
kv.lease_transfer_read_summary.local_budget
byte size4.0 MiBcontrols the maximum number of bytes that will be used to summarize the local segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Advanced/Self-Hosted
kv.log_range_and_node_events.enabled
booleantrueset to true to transactionally log range events (e.g., split, merge, add/remove voter/non-voter) into system.rangelogand node join and restart events into system.eventologAdvanced/Self-Hosted
kv.protectedts.reconciliation.interval
duration5m0sthe frequency for reconciling jobs with protected timestamp recordsAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.raft.leader_fortification.fraction_enabled
float1controls the fraction of ranges for which the raft leader fortification protocol is enabled. Leader fortification is needed for a range to use a Leader lease. Set to 0.0 to disable leader fortification and, by extension, Leader leases. Set to 1.0 to enable leader fortification for all ranges and, by extension, use Leader leases for all ranges which do not require expiration-based leases. Set to a value between 0.0 and 1.0 to gradually roll out Leader leases across the ranges in a cluster.Advanced/Self-Hosted
kv.range.range_size_hard_cap
byte size8.0 GiBhard cap on the maximum size a range is allowed to grow to withoutsplitting before writes to the range are blocked. Takes precedence over all other configurationsAdvanced/Self-Hosted
kv.range_split.by_load.enabled
(alias: kv.range_split.by_load_enabled)
booleantrueallow automatic splits of ranges based on where load is concentratedAdvanced/Self-Hosted
kv.range_split.load_cpu_threshold
duration500msthe CPU use per second over which, the range becomes a candidate for load based splittingAdvanced/Self-Hosted
kv.range_split.load_qps_threshold
integer2500the QPS over which, the range becomes a candidate for load based splittingAdvanced/Self-Hosted
kv.rangefeed.client.stream_startup_rate
integer100controls the rate per second the client will initiate new rangefeed stream for a single range; 0 implies unlimitedBasic/Standard/Advanced/Self-Hosted
kv.rangefeed.closed_timestamp_refresh_interval
duration3sthe interval at which closed-timestamp updatesare delivered to rangefeeds; set to 0 to use kv.closed_timestamp.side_transport_intervalAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.rangefeed.enabled
booleanfalseif set, rangefeed registration is enabledAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.replica_circuit_breaker.slow_replication_threshold
duration1m0sduration after which slow proposals trip the per-Replica circuit breaker (zero duration disables breakers)Advanced/Self-Hosted
kv.replica_raft.leaderless_unavailable_threshold
duration1m0sduration after which leaderless replicas is considered unavailable. Set to 0 to disable leaderless replica availability checksAdvanced/Self-Hosted
kv.replica_stats.addsst_request_size_factor
integer50000the divisor that is applied to addsstable request sizes, then recorded in a leaseholders QPS; 0 means all requests are treated as cost 1Advanced/Self-Hosted
kv.replication_reports.interval
duration1m0sthe frequency for generating the replication_constraint_stats, replication_stats_report and replication_critical_localities reports (set to 0 to disable)Advanced/Self-Hosted
kv.snapshot_rebalance.max_rate
byte size32 MiBthe rate limit (bytes/sec) to use for rebalance and upreplication snapshotsAdvanced/Self-Hosted
kv.transaction.max_intents_and_locks
integer0maximum count of inserts or durable locks for a single transactions, 0 to disableBasic/Standard/Advanced/Self-Hosted
kv.transaction.max_intents_bytes
integer4194304maximum number of bytes used to track locks in transactionsBasic/Standard/Advanced/Self-Hosted
kv.transaction.max_refresh_spans_bytes
integer4194304maximum number of bytes used to track refresh spans in serializable transactionsBasic/Standard/Advanced/Self-Hosted
kv.transaction.randomized_anchor_key.enabled
booleanfalsedictates whether a transactions anchor key is randomized or notBasic/Standard/Advanced/Self-Hosted
kv.transaction.reject_over_max_intents_budget.enabled
booleanfalseif set, transactions that exceed their lock tracking budget (kv.transaction.max_intents_bytes) are rejected instead of having their lock spans imprecisely compressedBasic/Standard/Advanced/Self-Hosted
kv.transaction.write_pipelining.locking_reads.enabled
booleantrueif enabled, transactional locking reads are pipelined through Raft consensusBasic/Standard/Advanced/Self-Hosted
kv.transaction.write_pipelining.ranged_writes.enabled
booleantrueif enabled, transactional ranged writes are pipelined through Raft consensusBasic/Standard/Advanced/Self-Hosted
kv.transaction.write_pipelining.enabled
(alias: kv.transaction.write_pipelining_enabled)
booleantrueif enabled, transactional writes are pipelined through Raft consensusBasic/Standard/Advanced/Self-Hosted
kv.transaction.write_pipelining.max_batch_size
(alias: kv.transaction.write_pipelining_max_batch_size)
integer128if non-zero, defines that maximum size batch that will be pipelined through Raft consensusBasic/Standard/Advanced/Self-Hosted
kvadmission.store.provisioned_bandwidth
byte size0 Bif set to a non-zero value, this is used as the provisioned bandwidth (in bytes/s), for each store. It can be overridden on a per-store basis using the --store flag. Note that setting the provisioned bandwidth to a positive value may enable disk bandwidth based admission control, since admission.disk_bandwidth_tokens.elastic.enabled defaults to trueAdvanced/Self-Hosted
kvadmission.store.snapshot_ingest_bandwidth_control.enabled
booleantrueif set to true, snapshot ingests will be subject to disk write control in ACAdvanced/Self-Hosted
log.channel_compatibility_mode.enabled
booleanfalsewhen true, logs will to log to their legacy (pre 26.1) logging channels; when false, logs will be logged to new logging channelsBasic/Standard/Advanced/Self-Hosted
obs.tablemetadata.automatic_updates.enabled
booleanfalseenables automatic updates of the table metadata cache system.table_metadataBasic/Standard/Advanced/Self-Hosted
obs.tablemetadata.data_valid_duration
duration20m0sthe duration for which the data in system.table_metadata is considered validBasic/Standard/Advanced/Self-Hosted
schedules.backup.gc_protection.enabled
booleantrueenable chaining of GC protection across backups run as part of a scheduleBasic/Standard/Advanced/Self-Hosted
security.client_cert.subject_required.enabled
booleanfalsemandates a requirement for subject role to be set for db userAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
security.ocsp.mode
enumerationoffuse OCSP to check whether TLS certificates are revoked. If the OCSP server is unreachable, in strict mode all certificates will be rejected and in lax mode all certificates will be accepted. [off = 0, lax = 1, strict = 2]Basic/Standard/Advanced/Self-Hosted
security.ocsp.timeout
duration3stimeout before considering the OCSP server unreachableBasic/Standard/Advanced/Self-Hosted
security.provisioning.ldap.enabled
booleanfalseenables automatic creation of SQL users upon successful LDAP loginBasic/Standard/Advanced/Self-Hosted
server.auth_log.sql_connections.enabled
booleanfalseif set, log SQL client connect and disconnect events to the SESSIONS log channel (note: may hinder performance on loaded nodes)Basic/Standard/Advanced/Self-Hosted
server.auth_log.sql_sessions.enabled
booleanfalseif set, log verbose SQL session authentication events to the SESSIONS log channel (note: may hinder performance on loaded nodes). Session start and end events are always logged regardless of this setting; disable the SESSIONS log channel to suppress them.Basic/Standard/Advanced/Self-Hosted
server.authentication_cache.enabled
booleantrueenables a cache used during authentication to avoid lookups to system tables when retrieving per-user authentication-related informationBasic/Standard/Advanced/Self-Hosted
server.child_metrics.enabled
booleanfalseenables the exporting of child metrics, additional prometheus time series with extra labelsBasic/Standard/Advanced/Self-Hosted
server.child_metrics.include_aggregate.enabled
booleantrueinclude the reporting of the aggregate time series when child metrics are enabled. This cluster setting has no effect if child metrics are disabled.Basic/Standard/Advanced/Self-Hosted
server.clock.forward_jump_check.enabled
(alias: server.clock.forward_jump_check_enabled)
booleanfalseif enabled, forward clock jumps > max_offset/2 will cause a panicBasic/Standard/Advanced/Self-Hosted
server.clock.persist_upper_bound_interval
duration0sthe interval between persisting the wall time upper bound of the clock. The clock does not generate a wall time greater than the persisted timestamp and will panic if it sees a wall time greater than this value. When cockroach starts, it waits for the wall time to catch-up till this persisted timestamp. This guarantees monotonic wall time across server restarts. Not setting this or setting a value of 0 disables this feature.Basic/Standard/Advanced/Self-Hosted
server.consistency_check.max_rate
byte size8.0 MiBthe rate limit (bytes/sec) to use for consistency checks; used in conjunction with server.consistency_check.interval to control the frequency of consistency checks. Note that setting this too high can negatively impact performance.Advanced/Self-Hosted
server.eventlog.enabled
booleantrueif set, logged notable events are also stored in the table system.eventlogBasic/Standard/Advanced/Self-Hosted
server.eventlog.ttl
duration2160h0m0sif nonzero, entries in system.eventlog older than this duration are periodically purgedBasic/Standard/Advanced/Self-Hosted
server.host_based_authentication.configuration
stringhost-based authentication configuration to use during connection authenticationBasic/Standard/Advanced/Self-Hosted
server.hot_ranges_request.node.timeout
duration5m0sthe duration allowed for a single node to return hot range data before the request is cancelled; if set to 0, there is no timeoutBasic/Standard/Advanced/Self-Hosted
server.hsts.enabled
booleanfalseif true, HSTS headers will be sent along with all HTTP requests. The headers will contain a max-age setting of one year. Browsers honoring the header will always use HTTPS to access the DB Console. Ensure that TLS is correctly configured prior to enabling.Basic/Standard/Advanced/Self-Hosted
server.http.base_path
string/path to redirect the user to upon succcessful loginBasic/Standard/Advanced/Self-Hosted
server.identity_map.configuration
stringsystem-identity to database-username mappingsBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.audience
stringsets accepted audience values for JWT logins over the SQL interfaceBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.claim
stringsets the JWT claim that is parsed to get the usernameBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.client.timeout
duration15ssets the client timeout for external calls made during JWT authentication (e.g. fetching JWKS, etc.)Basic/Standard/Advanced/Self-Hosted
server.jwt_authentication.enabled
booleanfalseenables or disables JWT login for the SQL interfaceBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.issuers.configuration
(alias: server.jwt_authentication.issuers)
stringsets accepted issuer values for JWT logins over the SQL interface which can be a single issuer URL string or a JSON string containing an array of issuer URLs or a JSON object containing map of issuer URLS to JWKS URIsBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.issuers.custom_ca
stringsets the PEM encoded custom root CA for verifying certificates while fetching JWKSBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.jwks
string{"keys":[]}sets the public key set for JWT logins over the SQL interface (JWKS format)Basic/Standard/Advanced/Self-Hosted
server.jwt_authentication.jwks_auto_fetch.enabled
booleanfalseenables or disables automatic fetching of JWKS from the issuer's well-known endpoint or JWKS URI set in JWTAuthIssuersConfig. If this is enabled, the server.jwt_authentication.jwks will be ignored.Basic/Standard/Advanced/Self-Hosted
server.ldap_authentication.client.tls_certificate
stringsets the client certificate PEM for establishing mTLS connection with LDAP serverBasic/Standard/Advanced/Self-Hosted
server.ldap_authentication.client.tls_key
stringsets the client key PEM for establishing mTLS connection with LDAP serverBasic/Standard/Advanced/Self-Hosted
server.ldap_authentication.domain.custom_ca
stringsets the PEM encoded custom root CA for verifying domain certificates when establishing connection with LDAP serverBasic/Standard/Advanced/Self-Hosted
server.log_gc.max_deletions_per_cycle
integer1000the maximum number of entries to delete on each purge of log-like system tablesBasic/Standard/Advanced/Self-Hosted
server.log_gc.period
duration1h0m0sthe period at which log-like system tables are checked for old entriesBasic/Standard/Advanced/Self-Hosted
server.max_connections_per_gateway
integer-1the maximum number of SQL connections per gateway allowed at a given time (note: this will only limit future connection attempts and will not affect already established connections). Negative values result in unlimited number of connections. Superusers are not affected by this limit.Basic/Standard/Advanced/Self-Hosted
server.max_open_transactions_per_gateway
integer-1the maximum number of open SQL transactions per gateway allowed at a given time. Negative values result in unlimited number of connections. Superusers are not affected by this limit.Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.autologin.enabled
(alias: server.oidc_authentication.autologin)
booleanfalseif true, logged-out visitors to the DB Console will be automatically redirected to the OIDC login endpointBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.button_text
stringLog in with your OIDC providertext to show on button on DB Console login page to login with your OIDC provider (only shown if OIDC is enabled)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.claim_json_key
stringsets JSON key of principal to extract from payload after OIDC authentication completes (usually email or sid)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.client.timeout
duration15ssets the client timeout for external calls made during OIDC authentication (e.g. authorization code flow, etc.)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.client_id
stringsets OIDC client idBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.client_secret
stringsets OIDC client secretBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.enabled
booleanfalseenables or disabled OIDC login for the DB ConsoleBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.principal_regex
string(.+)regular expression to apply to extracted principal (see claim_json_key setting) to translate to SQL user (golang regex format, must include 1 grouping to extract)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.provider.custom_ca
stringsets the PEM encoded custom root CA for verifying certificates while authenticating through the OIDC providerBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.provider_url
stringsets OIDC provider URL ({provider_url}/.well-known/openid-configuration must resolve)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.redirect_url
stringhttps://localhost:8080/oidc/v1/callbacksets OIDC redirect URL via a URL string or a JSON string containing a required `redirect_urls` key with an object that maps from region keys to URL strings (URLs should point to your load balancer and must route to the path /oidc/v1/callback)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.scopes
stringopenidsets OIDC scopes to include with authentication request (space delimited list of strings, required to start with `openid`)Basic/Standard/Advanced/Self-Hosted
server.rangelog.ttl
duration720h0m0sif nonzero, entries in system.rangelog older than this duration are periodically purgedAdvanced/Self-Hosted
server.redact_sensitive_settings.enabled
booleanfalseenables or disables the redaction of sensitive settings in the output of SHOW CLUSTER SETTINGS and SHOW ALL CLUSTER SETTINGS for users without the MODIFYCLUSTERSETTING privilegeBasic/Standard/Advanced/Self-Hosted
server.shutdown.connections.timeout
(alias: server.shutdown.connection_wait)
duration0sthe maximum amount of time a server waits for all SQL connections to be closed before proceeding with a drain. (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Basic/Standard/Advanced/Self-Hosted
server.shutdown.initial_wait
(alias: server.shutdown.drain_wait)
duration0sthe amount of time a server waits in an unready state before proceeding with a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting. --drain-wait is to specify the duration of the whole draining process, while server.shutdown.initial_wait is to set the wait time for health probes to notice that the node is not ready.)Basic/Standard/Advanced/Self-Hosted
server.shutdown.lease_transfer_iteration.timeout
(alias: server.shutdown.lease_transfer_wait)
duration5sthe timeout for a single iteration of the range lease transfer phase of draining (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Advanced/Self-Hosted
server.shutdown.transactions.timeout
(alias: server.shutdown.query_wait)
duration10sthe timeout for waiting for active transactions to finish during a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Basic/Standard/Advanced/Self-Hosted
server.sql_tcp_keep_alive.count
integer3maximum number of probes that will be sent out before a connection is dropped because it's unresponsive (Linux and Darwin only)Basic/Standard/Advanced/Self-Hosted
server.sql_tcp_keep_alive.interval
duration10stime between keep alive probes and idle time before probes are sent outBasic/Standard/Advanced/Self-Hosted
server.time_until_store_dead
duration5m0sthe time after which if there is no new gossiped information about a store, it is considered deadBasic/Standard/Advanced/Self-Hosted
server.user_login.cert_password_method.auto_scram_promotion.enabled
booleantruewhether to automatically promote cert-password authentication to use SCRAMBasic/Standard/Advanced/Self-Hosted
server.user_login.downgrade_scram_stored_passwords_to_bcrypt.enabled
booleantrueif server.user_login.password_encryption=crdb-bcrypt, this controls whether to automatically re-encode stored passwords using scram-sha-256 to crdb-bcryptBasic/Standard/Advanced/Self-Hosted
server.user_login.min_password_length
integer1the minimum length accepted for passwords set in cleartext via SQL. Note that a value lower than 1 is ignored: passwords cannot be empty in any case. This setting only applies when adding new users or altering an existing user's password; it will not affect existing logins.Basic/Standard/Advanced/Self-Hosted
server.user_login.password_encryption
enumerationscram-sha-256which hash method to use to encode cleartext passwords passed via ALTER/CREATE USER/ROLE WITH PASSWORD [crdb-bcrypt = 2, scram-sha-256 = 3]Basic/Standard/Advanced/Self-Hosted
server.user_login.password_hashes.default_cost.crdb_bcrypt
integer10the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method crdb-bcrypt (allowed range: 4-31)Basic/Standard/Advanced/Self-Hosted
server.user_login.password_hashes.default_cost.scram_sha_256
integer10610the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method scram-sha-256 (allowed range: 4096-240000000000)Basic/Standard/Advanced/Self-Hosted
server.user_login.rehash_scram_stored_passwords_on_cost_change.enabled
booleantrueif server.user_login.password_hashes.default_cost.scram_sha_256 differs from, the cost in a stored hash, this controls whether to automatically re-encode stored passwords using scram-sha-256 with the new default costBasic/Standard/Advanced/Self-Hosted
server.user_login.timeout
duration10stimeout after which client authentication times out if some system range is unavailable (0 = no timeout)Basic/Standard/Advanced/Self-Hosted
server.user_login.upgrade_bcrypt_stored_passwords_to_scram.enabled
booleantrueif server.user_login.password_encryption=scram-sha-256, this controls whether to automatically re-encode stored passwords using crdb-bcrypt to scram-sha-256Basic/Standard/Advanced/Self-Hosted
server.web_session.purge.ttl
duration1h0m0sif nonzero, entries in system.web_sessions older than this duration are periodically purgedBasic/Standard/Advanced/Self-Hosted
server.web_session.timeout
(alias: server.web_session_timeout)
duration168h0m0sthe duration that a newly created web session will be validBasic/Standard/Advanced/Self-Hosted
spanconfig.bounds.enabled
booleantruedictates whether span config bounds are consulted when serving span configs for secondary tenantsAdvanced/Self-Hosted
spanconfig.range_coalescing.system.enabled
(alias: spanconfig.storage_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs, for the ranges specific to the system tenantAdvanced/Self-Hosted
spanconfig.range_coalescing.application.enabled
(alias: spanconfig.tenant_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs across all secondary tenant keyspacesAdvanced/Self-Hosted
sql.auth.change_own_password.enabled
booleanfalsecontrols whether a user is allowed to change their own password, even if they have no other privilegesBasic/Standard/Advanced/Self-Hosted
sql.auth.grant_option_for_owner.enabled
booleantruedetermines whether the GRANT OPTION for privileges is implicitly given to the owner of an objectBasic/Standard/Advanced/Self-Hosted
sql.auth.grant_option_inheritance.enabled
booleantruedetermines whether the GRANT OPTION for privileges is inherited through role membershipBasic/Standard/Advanced/Self-Hosted
sql.auth.public_schema_create_privilege.enabled
booleantruedetermines whether to grant all users the CREATE privileges on the public schema when it is createdBasic/Standard/Advanced/Self-Hosted
sql.auth.skip_underlying_view_privilege_checks.enabled
booleantruedetermines whether to skip privilege checks on tables underlying views. When enabled, users with SELECT privileges on a view can query it regardless of their privileges on the underlying tables, and row-level security policies are evaluated as the invoking user rather than the view owner. This restores pre-v26.2 behavior.Basic/Standard/Advanced/Self-Hosted
sql.catalog.allow_leased_descriptors.enabled
booleantrueif true, catalog views (crdb_internal, information_schema, pg_catalog) can use leased descriptors for improved performanceBasic/Standard/Advanced/Self-Hosted
sql.closed_session_cache.capacity
integer1000the maximum number of sessions in the cacheBasic/Standard/Advanced/Self-Hosted
sql.closed_session_cache.time_to_live
integer3600the maximum time to live, in secondsBasic/Standard/Advanced/Self-Hosted
sql.contention.event_store.capacity
byte size64 MiBthe in-memory storage capacity per-node of contention event storeBasic/Standard/Advanced/Self-Hosted
sql.contention.event_store.duration_threshold
duration0sminimum contention duration to cause the contention events to be collected into crdb_internal.transaction_contention_eventsBasic/Standard/Advanced/Self-Hosted
sql.contention.record_serialization_conflicts.enabled
booleantrueenables recording 40001 errors with conflicting txn meta as SERIALIZATION_CONFLICTcontention events into crdb_internal.transaction_contention_eventsBasic/Standard/Advanced/Self-Hosted
sql.contention.txn_id_cache.max_size
byte size64 MiBthe maximum byte size TxnID cache will use (set to 0 to disable)Basic/Standard/Advanced/Self-Hosted
sql.cross_db_fks.enabled
booleanfalseif true, creating foreign key references across databases is allowedBasic/Standard/Advanced/Self-Hosted
sql.cross_db_sequence_owners.enabled
booleanfalseif true, creating sequences owned by tables from other databases is allowedBasic/Standard/Advanced/Self-Hosted
sql.cross_db_sequence_references.enabled
booleanfalseif true, sequences referenced by tables from other databases are allowedBasic/Standard/Advanced/Self-Hosted
sql.cross_db_views.enabled
booleanfalseif true, creating views that refer to other databases is allowedBasic/Standard/Advanced/Self-Hosted
sql.defaults.cost_scans_with_default_col_size.enabled
booleanfalsesetting to true uses the same size for all columns to compute scan cost
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.datestyle
enumerationiso, mdydefault value for DateStyle session setting [iso, mdy = 0, iso, dmy = 1, iso, ymd = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.default_hash_sharded_index_bucket_count
integer16used as bucket count if bucket count is not specified in hash sharded index definition
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.default_int_size
integer8the size, in bytes, of an INT type
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.disallow_full_table_scans.enabled
booleanfalsesetting to true rejects queries that have planned a full table scan; set large_full_scan_rows > 0 to allow small full table scans estimated to read fewer than large_full_scan_rows
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.distsql
enumerationautodefault distributed SQL execution mode [off = 0, auto = 1, on = 2, always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_alter_column_type.enabled
booleanfalsedefault value for experimental_alter_column_type session setting; enables the use of ALTER COLUMN TYPE for general conversions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_distsql_planning
enumerationoffdefault experimental_distsql_planning mode; enables experimental opt-driven DistSQL planning [off = 0, on = 1]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_enable_unique_without_index_constraints.enabled
booleanfalsedefault value for experimental_enable_unique_without_index_constraints session setting;disables unique without index constraints by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_implicit_column_partitioning.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for the use of implicit column partitioning
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_temporary_tables.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for use of temporary tables by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.foreign_key_cascades_limit
integer10000default value for foreign_key_cascades_limit session setting; limits the number of cascading operations that run as part of a single query
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.idle_in_session_timeout
duration0sdefault value for the idle_in_session_timeout; default value for the idle_in_session_timeout session setting; controls the duration a session is permitted to idle before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.idle_in_transaction_session_timeout
duration0sdefault value for the idle_in_transaction_session_timeout; controls the duration a session is permitted to idle in a transaction before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.implicit_select_for_update.enabled
booleantruedefault value for enable_implicit_select_for_update session setting; enables FOR UPDATE locking during the row-fetch phase of mutation statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.insert_fast_path.enabled
booleantruedefault value for enable_insert_fast_path session setting; enables a specialized insert path
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.intervalstyle
enumerationpostgresdefault value for IntervalStyle session setting [postgres = 0, iso_8601 = 1, sql_standard = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.large_full_scan_rows
float0default value for large_full_scan_rows session variable which determines the table size at which full scans are considered large and disallowed when disallow_full_table_scans is set to true; set to 0 to reject all full table or full index scans when disallow_full_table_scans is true
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.locality_optimized_partitioned_index_scan.enabled
booleantruedefault value for locality_optimized_partitioned_index_scan session setting; enables searching for rows in the current region before searching remote regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.lock_timeout
duration0sdefault value for the lock_timeout; default value for the lock_timeout session setting; controls the duration a query is permitted to wait while attempting to acquire a lock on a key or while blocking on an existing lock in order to perform a non-locking read on a key; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.on_update_rehome_row.enabled
booleantruedefault value for on_update_rehome_row; enables ON UPDATE rehome_row() expressions to trigger on updates
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.optimizer_use_histograms.enabled
booleantruedefault value for optimizer_use_histograms session setting; enables usage of histograms in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.optimizer_use_multicol_stats.enabled
booleantruedefault value for optimizer_use_multicol_stats session setting; enables usage of multi-column stats in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.override_alter_primary_region_in_super_region.enabled
booleanfalsedefault value for override_alter_primary_region_in_super_region; allows for altering the primary region even if the primary region is a member of a super region
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.override_multi_region_zone_config.enabled
booleanfalsedefault value for override_multi_region_zone_config; allows for overriding the zone configs of a multi-region table or database
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.prefer_lookup_joins_for_fks.enabled
booleanfalsedefault value for prefer_lookup_joins_for_fks session setting; causes foreign key operations to use lookup joins when possible
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.primary_region
stringif not empty, all databases created without a PRIMARY REGION will implicitly have the given PRIMARY REGION
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.reorder_joins_limit
integer8default number of joins to reorder
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.require_explicit_primary_keys.enabled
booleanfalsedefault value for requiring explicit primary keys in CREATE TABLE statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.results_buffer.size
byte size512 KiBdefault size of the buffer that accumulates results for a statement or a batch of statements before they are sent to the client. This can be overridden on an individual connection with the 'results_buffer_size' parameter. Note that auto-retries generally only happen while no results have been delivered to the client, so reducing this size can increase the number of retriable errors a client receives. On the other hand, increasing the buffer size can increase the delay until the client receives the first result row. Updating the setting only affects new connections. Setting to 0 disables any buffering.
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.serial_normalization
enumerationrowiddefault handling of SERIAL in table definitions [rowid = 0, virtual_sequence = 1, sql_sequence = 2, sql_sequence_cached = 3, unordered_rowid = 4, sql_sequence_cached_node = 5]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.statement_timeout
duration0sdefault value for the statement_timeout; default value for the statement_timeout session setting; controls the duration a query is permitted to run before it is canceled; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.stub_catalog_tables.enabled
booleantruedefault value for stub_catalog_tables session setting
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.super_regions.enabled
booleanfalsedefault value for enable_super_regions; allows for the usage of super regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.transaction_rows_read_err
integer0the limit for the number of rows read by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.transaction_rows_read_log
integer0the threshold for the number of rows read by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.transaction_rows_written_err
integer0the limit for the number of rows written by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.transaction_rows_written_log
integer0the threshold for the number of rows written by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.use_declarative_schema_changer
enumerationondefault value for use_declarative_schema_changer session setting;disables new schema changer by default [off = 0, on = 1, unsafe = 2, unsafe_always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.vectorize
enumerationondefault vectorize mode [on = 0, on = 1, on = 2, experimental_always = 3, off = 4]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.zigzag_join.enabled
booleanfalsedefault value for enable_zigzag_join session setting; disallows use of zig-zag join by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.distsql.temp_storage.workmem
byte size64 MiBmaximum amount of memory in bytes a processor can use before falling back to temp storageBasic/Standard/Advanced/Self-Hosted
sql.guardrails.max_row_size_err
byte size512 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an error is returned; use 0 to disableBasic/Standard/Advanced/Self-Hosted
sql.guardrails.max_row_size_log
byte size64 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an event is logged to SQL_PERF (or SQL_INTERNAL_PERF if the mutating statement was internal); use 0 to disableBasic/Standard/Advanced/Self-Hosted
sql.hash_sharded_range_pre_split.max
integer16max pre-split ranges to have when adding hash sharded index to an existing tableBasic/Standard/Advanced/Self-Hosted
sql.index_recommendation.drop_unused_duration
duration168h0m0sthe index unused duration at which we begin to recommend dropping the indexBasic/Standard/Advanced/Self-Hosted
sql.insights.anomaly_detection.enabled
booleantrueenable per-fingerprint latency recording and anomaly detectionBasic/Standard/Advanced/Self-Hosted
sql.insights.anomaly_detection.latency_threshold
duration50msstatements must surpass this threshold to trigger anomaly detection and identificationBasic/Standard/Advanced/Self-Hosted
sql.insights.anomaly_detection.memory_limit
byte size1.0 MiBthe maximum amount of memory allowed for tracking statement latenciesBasic/Standard/Advanced/Self-Hosted
sql.insights.execution_insights_capacity
integer1000the size of the per-node store of execution insightsBasic/Standard/Advanced/Self-Hosted
sql.insights.high_retry_count.threshold
integer10the number of retries a slow statement must have undergone for its high retry count to be highlighted as a potential problemBasic/Standard/Advanced/Self-Hosted
sql.insights.latency_threshold
duration100msamount of time after which an executing statement is considered slow. Use 0 to disable.Basic/Standard/Advanced/Self-Hosted
sql.log.redact_names.enabled
booleanfalseif set, schema object identifers are redacted in SQL statements that appear in event logsBasic/Standard/Advanced/Self-Hosted
sql.log.scan_row_count_misestimate.enabled
booleanfalsewhen set to true, log a warning when a scan's actual row count differs significantly from the optimizer's estimateBasic/Standard/Advanced/Self-Hosted
sql.log.slow_query.experimental_full_table_scans.enabled
booleanfalsewhen set to true, statements that perform a full table/index scan will be logged to the slow query log even if they do not meet the latency threshold. Must have the slow query log enabled for this setting to have any effect.Basic/Standard/Advanced/Self-Hosted
sql.log.slow_query.internal_queries.enabled
booleanfalsewhen set to true, internal queries which exceed the slow query log threshold are logged to a separate log. Must have the slow query log enabled for this setting to have any effect.Basic/Standard/Advanced/Self-Hosted
sql.log.slow_query.latency_threshold
duration0swhen set to non-zero, log statements whose service latency exceeds the threshold to a secondary logger on each nodeBasic/Standard/Advanced/Self-Hosted
sql.log.user_audit
stringuser/role-based audit logging configuration. An enterprise license is required for this cluster setting to take effect.Basic/Standard/Advanced/Self-Hosted
sql.log.user_audit.reduced_config.enabled
booleanfalseenables logic to compute a reduced audit configuration, computing the audit configuration only once at session start instead of at each SQL event. The tradeoff with the increase in performance (~5%), is that changes to the audit configuration (user role memberships/cluster setting) are not reflected within session. Users will need to start a new session to see these changes in their auditing behaviour.Basic/Standard/Advanced/Self-Hosted
sql.metrics.application_name.enabled
booleanfalsewhen enabled, SQL metrics would export application name as and additional label as part of child metrics. The number of unique label combinations is limited to 5000 by default.Basic/Standard/Advanced/Self-Hosted
sql.metrics.database_name.enabled
booleanfalsewhen enabled, SQL metrics would export database name as and additional label as part of child metrics. The number of unique label combinations is limited to 5000 by default.Basic/Standard/Advanced/Self-Hosted
sql.metrics.index_usage_stats.enabled
booleantruecollect per index usage statisticsBasic/Standard/Advanced/Self-Hosted
sql.metrics.max_mem_reported_stmt_fingerprints
integer100000the maximum number of reported statement fingerprints stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.max_mem_reported_txn_fingerprints
integer100000the maximum number of reported transaction fingerprints stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.max_mem_stmt_fingerprints
integer7500the maximum number of statement fingerprints stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.max_mem_txn_fingerprints
integer7500the maximum number of transaction fingerprints stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.dump_to_logs.enabled
(alias: sql.metrics.statement_details.dump_to_logs)
booleanfalsedump collected statement statistics to node logs when periodically clearedBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.enabled
booleantruecollect per-statement query statisticsBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.gateway_node.enabled
booleanfalsesave the gateway node for each statement fingerprint. If false, the value will be stored as 0.Basic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.index_recommendation_collection.enabled
booleantruegenerate an index recommendation for each fingerprint IDBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.max_mem_reported_idx_recommendations
integer5000the maximum number of reported index recommendation info stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.threshold
duration0sminimum execution time to cause statement statistics to be collected. If configured, no transaction stats are collected.Basic/Standard/Advanced/Self-Hosted
sql.metrics.transaction_details.enabled
booleantruecollect per-application transaction statisticsBasic/Standard/Advanced/Self-Hosted
sql.multiple_modifications_of_table.enabled
booleanfalseif true, allow statements containing multiple INSERT ON CONFLICT, UPSERT, UPDATE, or DELETE subqueries modifying the same table, at the risk of data corruption if the same row is modified multiple times by a single statement (multiple INSERT subqueries without ON CONFLICT cannot cause corruption and are always allowed)Basic/Standard/Advanced/Self-Hosted
sql.multiregion.drop_primary_region.enabled
booleantrueallows dropping the PRIMARY REGION of a database if it is the last regionBasic/Standard/Advanced/Self-Hosted
sql.notices.enabled
booleantrueenable notices in the server/client protocol being sentBasic/Standard/Advanced/Self-Hosted
sql.optimizer.uniqueness_checks_for_gen_random_uuid.enabled
booleanfalseif enabled, uniqueness checks may be planned for mutations of UUID columns updated with gen_random_uuid(); otherwise, uniqueness is assumed due to near-zero collision probabilityBasic/Standard/Advanced/Self-Hosted
sql.schema.approx_max_object_count
integer20000approximate maximum number of schema objects allowed in the cluster; the check uses cached statistics, so the actual count may slightly exceed this limit; set to 0 to disableBasic/Standard/Advanced/Self-Hosted
sql.schema.auto_unlock.enabled
booleantruecontrols whether DDL operations will attempt to automatically unlock and re-lock schema_locked tables. When this setting is false, DDL on schema_locked tables is blocked unless the user manually unlocks the table first. The schema_locked storage parameter improves changefeed performance by locking the table's schema from the perspective of the changefeed.Basic/Standard/Advanced/Self-Hosted
sql.schema.telemetry.recurrence
string@weeklycron-tab recurrence for SQL schema telemetry jobAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
sql.spatial.experimental_box2d_comparison_operators.enabled
booleanfalseenables the use of certain experimental box2d comparison operatorsBasic/Standard/Advanced/Self-Hosted
sql.sqlcommenter.enabled
booleanfalseenables support for sqlcommenter. Key value parsed from sqlcommenter comments will be included in sql insights and sql logs. See https://google.github.io/sqlcommenter/ for more details.Basic/Standard/Advanced/Self-Hosted
sql.stats.activity.persisted_rows.max
integer200000maximum number of rows of statement and transaction activity that will be persisted in the system tablesBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_collection.enabled
booleantrueautomatic statistics collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_collection.fraction_stale_rows
float0.2target fraction of stale rows per table that will trigger a statistics refreshBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_collection.min_stale_rows
integer500target minimum number of stale rows per table that will trigger a statistics refreshBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_extremes_concurrency_limit
integer128determines the maximum number of concurrent automatic partial USING EXTREMES table statistics collection jobsBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_full_collection.enabled
booleantrueautomatic full statistics collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_full_concurrency_limit
integer1determines the maximum number of concurrent automatic full table statistics collection jobsBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_partial_collection.enabled
booleantrueautomatic partial statistics collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_partial_collection.fraction_stale_rows
float0.05target fraction of stale rows per table that will trigger a partial statistics refreshBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_partial_collection.min_stale_rows
integer100target minimum number of stale rows per table that will trigger a partial statistics refreshBasic/Standard/Advanced/Self-Hosted
sql.stats.cleanup.recurrence
string@hourlycron-tab recurrence for SQL Stats cleanup jobBasic/Standard/Advanced/Self-Hosted
sql.stats.detailed_latency_metrics.enabled
booleanfalselabel latency metrics with the statement fingerprint. Workloads with tens of thousands of distinct query fingerprints should leave this setting false. (experimental, affects performance for workloads with high fingerprint cardinality)Basic/Standard/Advanced/Self-Hosted
sql.stats.error_on_concurrent_create_stats.enabled
booleanfalseset to true to error on concurrent CREATE STATISTICS jobs, instead of skipping themBasic/Standard/Advanced/Self-Hosted
sql.stats.flush.enabled
booleantrueif set, SQL execution statistics are periodically flushed to diskBasic/Standard/Advanced/Self-Hosted
sql.stats.flush.interval
duration10m0sthe interval at which SQL execution statistics are flushed to disk, this value must be less than or equal to 1 hourBasic/Standard/Advanced/Self-Hosted
sql.stats.forecasts.enabled
booleantruewhen true, enables generation of statistics forecasts by default for all tablesBasic/Standard/Advanced/Self-Hosted
sql.stats.forecasts.max_decrease
float0.3333333333333333the most a prediction is allowed to decrease, expressed as the minimum ratio of the prediction to the lowest prior observationBasic/Standard/Advanced/Self-Hosted
sql.stats.forecasts.min_goodness_of_fit
float0.95the minimum R² (goodness of fit) measurement required from all predictive models to use a forecastBasic/Standard/Advanced/Self-Hosted
sql.stats.forecasts.min_observations
integer3the mimimum number of observed statistics required to produce a statistics forecastBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_buckets.count
integer200maximum number of histogram buckets to build during table statistics collectionBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_buckets.include_most_common_values.enabled
booleantruewhether to include most common values as histogram bucketsBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_buckets.max_fraction_most_common_values
float0.1maximum fraction of histogram buckets to use for most common valuesBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_collection.enabled
booleantruehistogram collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_samples.count
integer0number of rows sampled for histogram construction during table statistics collection. Not setting this or setting a value of 0 means that a reasonable sample size will be automatically picked based on the table size.Basic/Standard/Advanced/Self-Hosted
sql.stats.multi_column_collection.enabled
booleantruemulti-column statistics collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.non_default_columns.min_retention_period
duration24h0m0sminimum retention period for table statistics collected on non-default columnsBasic/Standard/Advanced/Self-Hosted
sql.stats.non_indexed_json_histograms.enabled
booleanfalseset to true to collect table statistics histograms on non-indexed JSON columnsBasic/Standard/Advanced/Self-Hosted
sql.stats.persisted_rows.max
integer1000000maximum number of rows of statement and transaction statistics that will be persisted in the system tables before compaction beginsBasic/Standard/Advanced/Self-Hosted
sql.stats.post_events.enabled
booleanfalseif set, an event is logged for every successful CREATE STATISTICS jobBasic/Standard/Advanced/Self-Hosted
sql.stats.response.max
integer20000the maximum number of statements and transaction stats returned in a CombinedStatements requestBasic/Standard/Advanced/Self-Hosted
sql.stats.response.show_internal.enabled
booleanfalsecontrols if statistics for internal executions should be returned by the CombinedStatements and if internal sessions should be returned by the ListSessions endpoints. These endpoints are used to display statistics on the SQL Activity pagesBasic/Standard/Advanced/Self-Hosted
sql.stats.system_tables.enabled
booleantruewhen true, enables use of statistics on system tables by the query optimizerBasic/Standard/Advanced/Self-Hosted
sql.stats.system_tables_autostats.enabled
booleantruewhen true, enables automatic collection of statistics on system tablesBasic/Standard/Advanced/Self-Hosted
sql.stats.table_statistics_cache.capacity
integer256the maximum number of table statistics entries stored in the LRU cache. Each cache entry corresponds to a single table.Basic/Standard/Advanced/Self-Hosted
sql.stats.virtual_computed_columns.enabled
booleantrueset to true to collect table statistics on virtual computed columnsBasic/Standard/Advanced/Self-Hosted
sql.telemetry.query_sampling.enabled
booleanfalsewhen set to true, executed queries will emit an event on the telemetry logging channelBasic/Standard/Advanced/Self-Hosted
sql.telemetry.query_sampling.internal.enabled
booleanfalsewhen set to true, internal queries will be sampled in telemetry loggingBasic/Standard/Advanced/Self-Hosted
sql.telemetry.query_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample executions for telemetry, note that it is recommended that this value shares a log-line limit of 10 logs per second on the telemetry pipeline with all other telemetry events. If sampling mode is set to 'transaction', this value is ignored.Basic/Standard/Advanced/Self-Hosted
sql.telemetry.query_sampling.mode
enumerationstatementthe execution level used for telemetry sampling. If set to 'statement', events are sampled at the statement execution level. If set to 'transaction', events are sampled at the transaction execution level, i.e. all statements for a transaction will be logged and are counted together as one sampled event (events are still emitted one per statement). [statement = 0, transaction = 1]Basic/Standard/Advanced/Self-Hosted
sql.telemetry.transaction_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample transactions for telemetry. If sampling mode is set to 'statement', this setting is ignored. In practice, this means that we only sample a transaction if 1/max_event_frequency seconds have elapsed since the last transaction was sampled.Basic/Standard/Advanced/Self-Hosted
sql.telemetry.transaction_sampling.statement_events_per_transaction.max
integer50the maximum number of statement events to log for every sampled transaction. Note that statements that are logged by force do not adhere to this limit.Basic/Standard/Advanced/Self-Hosted
sql.temp_object_cleaner.cleanup_interval
duration30m0show often to clean up orphaned temporary objectsBasic/Standard/Advanced/Self-Hosted
sql.temp_object_cleaner.wait_interval
duration30m0show long after creation a temporary object will be cleaned upBasic/Standard/Advanced/Self-Hosted
sql.log.all_statements.enabled
(alias: sql.trace.log_statement_execute)
booleanfalseset to true to enable logging of all executed statementsBasic/Standard/Advanced/Self-Hosted
sql.trace.stmt.enable_threshold
duration0senables tracing on all statements; statements executing for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting applies to individual statements within a transaction and is therefore finer-grained than sql.trace.txn.enable_thresholdBasic/Standard/Advanced/Self-Hosted
sql.trace.txn.enable_threshold
duration0senables transaction traces for transactions exceeding this duration, used with `sql.trace.txn.sample_rate`Basic/Standard/Advanced/Self-Hosted
sql.trace.txn.include_internal.enabled
booleantrueenables tracing internal transactions as well as external workload using sample rate and threshold settingsBasic/Standard/Advanced/Self-Hosted
sql.trace.txn.jaeger_json_output.enabled
booleanfalseenables Jaeger JSON output for transaction traces in logsBasic/Standard/Advanced/Self-Hosted
sql.trace.txn.sample_rate
float1enables probabilistic transaction tracing. It should be used in conjunction with `sql.trace.txn.enable_threshold`. A percentage of transactions between 0 and 1.0 will have tracing enabled, and only those which exceed the configured threshold will be logged.Basic/Standard/Advanced/Self-Hosted
sql.ttl.changefeed_replication.disabled
booleanfalseif true, deletes issued by TTL will not be replicated via changefeeds (this setting will be ignored by changefeeds that have the ignore_disable_changefeed_replication option set; such changefeeds will continue to replicate all TTL deletes)Basic/Standard/Advanced/Self-Hosted
sql.ttl.default_delete_batch_size
integer100default amount of rows to delete in a single query during a TTL jobBasic/Standard/Advanced/Self-Hosted
sql.ttl.default_delete_rate_limit
integer100default delete rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Basic/Standard/Advanced/Self-Hosted
sql.ttl.default_select_batch_size
integer500default amount of rows to select in a single query during a TTL jobBasic/Standard/Advanced/Self-Hosted
sql.ttl.default_select_rate_limit
integer0default select rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Basic/Standard/Advanced/Self-Hosted
sql.ttl.job.enabled
booleantruewhether the TTL job is enabledBasic/Standard/Advanced/Self-Hosted
sql.txn.read_committed_isolation.enabled
booleantrueset to true to allow transactions to use the READ COMMITTED isolation level if specified by BEGIN/SET commandsBasic/Standard/Advanced/Self-Hosted
sql.txn.repeatable_read_isolation.enabled
(alias: sql.txn.snapshot_isolation.enabled)
booleanfalseset to true to allow transactions to use the REPEATABLE READ isolation level if specified by BEGIN/SET commandsBasic/Standard/Advanced/Self-Hosted
sql.txn_fingerprint_id_cache.capacity
integer100the maximum number of txn fingerprint IDs storedBasic/Standard/Advanced/Self-Hosted
sql.vecindex.stalled_op.timeout
duration100msamount of time before other vector index workers will assist with a stalled background fixupBasic/Standard/Advanced/Self-Hosted
storage.delete_compaction_excise.enabled
booleantrueset to false to direct Pebble to not partially excise sstables in delete-only compactionsAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.ingest_split.enabled
booleantrueset to false to disable ingest-time splitting that lowers write-amplificationAdvanced/Self-Hosted
storage.ingestion.value_blocks.enabled
booleantrueset to true to enable writing of value blocks in ingestion sstablesBasic/Standard/Advanced/Self-Hosted
storage.max_sync_duration
duration20smaximum duration for disk operations; any operations that take longer than this setting trigger a warning log entry or process crashAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.max_sync_duration.fatal.enabled
booleantrueif true, fatal the process when a disk operation exceeds storage.max_sync_durationBasic/Standard/Advanced/Self-Hosted
storage.sstable.compression_algorithm
enumerationfastestdetermines the compression algorithm to use for Pebble stores [snappy = 1, zstd = 2, none = 3, minlz = 4, fastest = 5, balanced = 6, good = 7, fast = 8]Advanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.sstable.compression_algorithm_backup_storage
enumerationfastestdetermines the compression algorithm to use when compressing sstable data blocks for backup row data storage (fast,balanced,good are experimental); [snappy = 1, zstd = 2, none = 3, minlz = 4, fastest = 5, fast = 6, balanced = 7, good = 8]Advanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.sstable.compression_algorithm_backup_transport
enumerationfastestdetermines the compression algorithm to use when compressing sstable data blocks for backup transport (fast,balanced,good are experimental); [snappy = 1, zstd = 2, none = 3, minlz = 4, fastest = 5, fast = 6, balanced = 7, good = 8]Advanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.unhealthy_write_duration
duration20sduration for disk write operations, beyond which the disk will be reported as unhealthy for higher layer actionsAdvanced/Self-Hosted
storage.wal_failover.unhealthy_op_threshold
duration100msthe latency of a WAL write considered unhealthy and triggers a failover to a secondary WAL locationAdvanced/Self-Hosted
timeseries.storage.enabled
booleantrueif set, periodic timeseries data is stored within the cluster; disabling is not recommended unless you are storing the data elsewhereAdvanced/Self-Hosted
timeseries.storage.resolution_10s.ttl
duration240h0m0sthe maximum age of time series data stored at the 10 second resolution. Data older than this is subject to rollup and deletion.Advanced/Self-hosted (read-write); Basic/Standard (read-only)
timeseries.storage.resolution_1m.ttl
duration240h0m0sthe maximum age of time series data stored at the 1 minute resolution. Data older than this is subject to rollup and deletion.Advanced/Self-hosted (read-write); Basic/Standard (read-only)
timeseries.storage.resolution_30m.ttl
duration2160h0m0sthe maximum age of time series data stored at the 30 minute resolution. Data older than this is subject to deletion.Advanced/Self-hosted (read-write); Basic/Standard (read-only)
trace.debug_http_endpoint.enabled
(alias: trace.debug.enable)
booleanfalseif set, traces for recent requests can be seen at https://<ui>/debug/requestsBasic/Standard/Advanced/Self-Hosted
trace.opentelemetry.collector
stringaddress of an OpenTelemetry trace collector to receive traces using the otel gRPC protocol, as <host>:<port>. If no port is specified, 4317 will be used.Basic/Standard/Advanced/Self-Hosted
trace.snapshot.rate
duration0sif non-zero, interval at which background trace snapshots are capturedBasic/Standard/Advanced/Self-Hosted
trace.span_registry.enabled
booleanfalseif set, ongoing traces can be seen at https://<ui>/#/debug/tracezBasic/Standard/Advanced/Self-Hosted
trace.zipkin.collector
stringthe address of a Zipkin instance to receive traces, as <host>:<port>. If no port is specified, 9411 will be used.Basic/Standard/Advanced/Self-Hosted
ui.database_locality_metadata.enabled
booleantrueif enabled shows extended locality data about databases and tables in DB Console which can be expensive to computeBasic/Standard/Advanced/Self-Hosted
ui.default_timezone
stringthe default timezone used to format timestamps in the uiBasic/Standard/Advanced/Self-Hosted
ui.display_timezone
enumerationetc/utcthe timezone used to format timestamps in the ui. This setting is deprecatedand will be removed in a future version. Use the 'ui.default_timezone' setting instead. 'ui.default_timezone' takes precedence over this setting. [etc/utc = 0, america/new_york = 1]Basic/Standard/Advanced/Self-Hosted
version
version26.1set the active cluster version in the format '<major>.<minor>'Basic/Standard/Advanced/Self-Hosted
diff --git a/src/current/_includes/cockroach-generated/release-26.1/sql/aggregates.md b/src/current/_includes/cockroach-generated/release-26.1/sql/aggregates.md new file mode 100644 index 00000000000..1683084408b --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-26.1/sql/aggregates.md @@ -0,0 +1,589 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_agg(arg1: bool) → bool[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bool[]) → bool[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes) → bytes[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes[]) → bytes[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date) → date[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date[]) → date[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal) → decimal[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal[]) → decimal[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float) → float[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float[]) → float[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet) → inet[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet[]) → inet[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int) → int[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int[]) → int[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval) → interval[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval[]) → interval[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string) → string[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string[]) → string[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time) → time[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time[]) → time[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp) → timestamp[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp[]) → timestamp[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz) → timestamptz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz[]) → timestamptz[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid) → uuid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid[]) → uuid[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum) → anyenum[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum[]) → anyenum[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d) → box2d[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d[]) → box2d[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography) → geography[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography[]) → geography[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry) → geometry[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry[]) → geometry[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb) → jsonb[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb[]) → jsonb[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: ltree) → ltree[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: ltree[]) → ltree[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid) → oid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid[]) → oid[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn) → pg_lsn[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn[]) → pg_lsn[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor) → refcursor[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor[]) → refcursor[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz) → timetz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz[]) → timetz[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple) → tuple[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple[]) → tuple[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit) → varbit[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit[]) → varbit[][]

Aggregates the selected values into an array.

+		Immutable
array_cat_agg(arg1: bool[]) → bool[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: bytes[]) → bytes[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: date[]) → date[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: decimal[]) → decimal[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: float[]) → float[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: inet[]) → inet[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: int[]) → int[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: interval[]) → interval[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: string[]) → string[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: time[]) → time[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamp[]) → timestamp[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamptz[]) → timestamptz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: uuid[]) → uuid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: anyenum[]) → anyenum[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: box2d[]) → box2d[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geography[]) → geography[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geometry[]) → geometry[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: jsonb[]) → jsonb[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: ltree[]) → ltree[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: oid[]) → oid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: pg_lsn[]) → pg_lsn[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: refcursor[]) → refcursor[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timetz[]) → timetz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: tuple[]) → tuple[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: varbit[]) → varbit[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
avg(arg1: decimal) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: float) → float

Calculates the average of the selected values.

+		Immutable
avg(arg1: int) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: interval) → interval

Calculates the average of the selected values.

+		Immutable
bit_and(arg1: int) → int

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_and(arg1: varbit) → varbit

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: int) → int

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: varbit) → varbit

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bool_and(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
bool_or(arg1: bool) → bool

Calculates the boolean value of ORing all selected values.

+		Immutable
concat_agg(arg1: bytes) → bytes

Concatenates all selected values.

+		Immutable
concat_agg(arg1: string) → string

Concatenates all selected values.

+		Immutable
corr(arg1: decimal, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
count(arg1: anyelement) → int

Calculates the number of selected elements.

+		Immutable
count_rows() → int

Calculates the number of rows.

+		Immutable
covar_pop(arg1: decimal, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
every(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
json_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
json_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
jsonb_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
jsonb_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
max(arg1: bool) → bool

Identifies the maximum selected value.

+		Immutable
max(arg1: bytes) → bytes

Identifies the maximum selected value.

+		Immutable
max(arg1: date) → date

Identifies the maximum selected value.

+		Immutable
max(arg1: decimal) → decimal

Identifies the maximum selected value.

+		Immutable
max(arg1: float) → float

Identifies the maximum selected value.

+		Immutable
max(arg1: inet) → inet

Identifies the maximum selected value.

+		Immutable
max(arg1: int) → int

Identifies the maximum selected value.

+		Immutable
max(arg1: interval) → interval

Identifies the maximum selected value.

+		Immutable
max(arg1: string) → string

Identifies the maximum selected value.

+		Immutable
max(arg1: time) → time

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamp) → timestamp

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamptz) → timestamptz

Identifies the maximum selected value.

+		Immutable
max(arg1: uuid) → uuid

Identifies the maximum selected value.

+		Immutable
max(arg1: anyenum) → anyenum

Identifies the maximum selected value.

+		Immutable
max(arg1: box2d) → box2d

Identifies the maximum selected value.

+		Immutable
max(arg1: collatedstring{*}) → collatedstring{*}

Identifies the maximum selected value.

+		Immutable
max(arg1: geography) → geography

Identifies the maximum selected value.

+		Immutable
max(arg1: geometry) → geometry

Identifies the maximum selected value.

+		Immutable
max(arg1: jsonb) → jsonb

Identifies the maximum selected value.

+		Immutable
max(arg1: ltree) → ltree

Identifies the maximum selected value.

+		Immutable
max(arg1: oid) → oid

Identifies the maximum selected value.

+		Immutable
max(arg1: pg_lsn) → pg_lsn

Identifies the maximum selected value.

+		Immutable
max(arg1: timetz) → timetz

Identifies the maximum selected value.

+		Immutable
max(arg1: varbit) → varbit

Identifies the maximum selected value.

+		Immutable
min(arg1: bool) → bool

Identifies the minimum selected value.

+		Immutable
min(arg1: bytes) → bytes

Identifies the minimum selected value.

+		Immutable
min(arg1: date) → date

Identifies the minimum selected value.

+		Immutable
min(arg1: decimal) → decimal

Identifies the minimum selected value.

+		Immutable
min(arg1: float) → float

Identifies the minimum selected value.

+		Immutable
min(arg1: inet) → inet

Identifies the minimum selected value.

+		Immutable
min(arg1: int) → int

Identifies the minimum selected value.

+		Immutable
min(arg1: interval) → interval

Identifies the minimum selected value.

+		Immutable
min(arg1: string) → string

Identifies the minimum selected value.

+		Immutable
min(arg1: time) → time

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamp) → timestamp

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamptz) → timestamptz

Identifies the minimum selected value.

+		Immutable
min(arg1: uuid) → uuid

Identifies the minimum selected value.

+		Immutable
min(arg1: anyenum) → anyenum

Identifies the minimum selected value.

+		Immutable
min(arg1: box2d) → box2d

Identifies the minimum selected value.

+		Immutable
min(arg1: collatedstring{*}) → collatedstring{*}

Identifies the minimum selected value.

+		Immutable
min(arg1: geography) → geography

Identifies the minimum selected value.

+		Immutable
min(arg1: geometry) → geometry

Identifies the minimum selected value.

+		Immutable
min(arg1: jsonb) → jsonb

Identifies the minimum selected value.

+		Immutable
min(arg1: ltree) → ltree

Identifies the minimum selected value.

+		Immutable
min(arg1: oid) → oid

Identifies the minimum selected value.

+		Immutable
min(arg1: pg_lsn) → pg_lsn

Identifies the minimum selected value.

+		Immutable
min(arg1: timetz) → timetz

Identifies the minimum selected value.

+		Immutable
min(arg1: varbit) → varbit

Identifies the minimum selected value.

+		Immutable
percentile_cont(arg1: float) → float

Continuous percentile: returns a float corresponding to the specified fraction in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float) → interval

Continuous percentile: returns an interval corresponding to the specified fraction in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_cont(arg1: float[]) → float[]

Continuous percentile: returns floats corresponding to the specified fractions in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float[]) → interval[]

Continuous percentile: returns intervals corresponding to the specified fractions in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_disc(arg1: float) → anyelement

Discrete percentile: returns the first input value whose position in the ordering equals or exceeds the specified fraction.

+		Immutable
percentile_disc(arg1: float[]) → anyelement

Discrete percentile: returns input values whose position in the ordering equals or exceeds the specified fractions.

+		Immutable
regr_avgx(arg1: decimal, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_count(arg1: decimal, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_intercept(arg1: decimal, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_r2(arg1: decimal, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_slope(arg1: decimal, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_sxx(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
sqrdiff(arg1: decimal) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: float) → float

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: int) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
st_collect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_extent(arg1: geometry) → box2d

Forms a Box2D that encapsulates all provided geometries.

+		Immutable
st_makeline(arg1: geometry) → geometry

Forms a LineString from Point, MultiPoint or LineStrings. Other shapes will be ignored.

+		Immutable
st_memcollect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_memunion(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
st_union(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
stddev(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: decimal) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: float) → float

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: int) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
string_agg(arg1: bytes, arg2: bytes) → bytes

Concatenates all selected values using the provided delimiter.

+		Immutable
string_agg(arg1: string, arg2: string) → string

Concatenates all selected values using the provided delimiter.

+		Immutable
sum(arg1: decimal) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: float) → float

Calculates the sum of the selected values.

+		Immutable
sum(arg1: int) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: interval) → interval

Calculates the sum of the selected values.

+		Immutable
sum_int(arg1: int) → int

Calculates the sum of the selected values.

+		Immutable
var_pop(arg1: decimal) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: float) → float

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: int) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_samp(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
variance(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
xor_agg(arg1: bytes) → bytes

Calculates the bitwise XOR of the selected values.

+		Immutable
xor_agg(arg1: int) → int

Calculates the bitwise XOR of the selected values.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-26.1/sql/functions.md b/src/current/_includes/cockroach-generated/release-26.1/sql/functions.md new file mode 100644 index 00000000000..a06f3f3ae09 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-26.1/sql/functions.md @@ -0,0 +1,3680 @@ +### Array functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_append(array: bool[], elem: bool) → bool[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: bytes[], elem: bytes) → bytes[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: date[], elem: date) → date[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: decimal[], elem: decimal) → decimal[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: float[], elem: float) → float[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: inet[], elem: inet) → inet[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: int[], elem: int) → int[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: interval[], elem: interval) → interval[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: string[], elem: string) → string[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: time[], elem: time) → time[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamp[], elem: timestamp) → timestamp[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamptz[], elem: timestamptz) → timestamptz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: uuid[], elem: uuid) → uuid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: anyenum[], elem: anyenum) → anyenum[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: box2d[], elem: box2d) → box2d[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geography[], elem: geography) → geography[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geometry[], elem: geometry) → geometry[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: jsonb[], elem: jsonb) → jsonb[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: ltree[], elem: ltree) → ltree[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: oid[], elem: oid) → oid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: refcursor[], elem: refcursor) → refcursor[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timetz[], elem: timetz) → timetz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: tuple[], elem: tuple) → tuple[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: varbit[], elem: varbit) → varbit[]

Appends elem to array, returning the result.

+		Immutable
array_cat(left: bool[], right: bool[]) → bool[]

Appends two arrays.

+		Immutable
array_cat(left: bytes[], right: bytes[]) → bytes[]

Appends two arrays.

+		Immutable
array_cat(left: date[], right: date[]) → date[]

Appends two arrays.

+		Immutable
array_cat(left: decimal[], right: decimal[]) → decimal[]

Appends two arrays.

+		Immutable
array_cat(left: float[], right: float[]) → float[]

Appends two arrays.

+		Immutable
array_cat(left: inet[], right: inet[]) → inet[]

Appends two arrays.

+		Immutable
array_cat(left: int[], right: int[]) → int[]

Appends two arrays.

+		Immutable
array_cat(left: interval[], right: interval[]) → interval[]

Appends two arrays.

+		Immutable
array_cat(left: string[], right: string[]) → string[]

Appends two arrays.

+		Immutable
array_cat(left: time[], right: time[]) → time[]

Appends two arrays.

+		Immutable
array_cat(left: timestamp[], right: timestamp[]) → timestamp[]

Appends two arrays.

+		Immutable
array_cat(left: timestamptz[], right: timestamptz[]) → timestamptz[]

Appends two arrays.

+		Immutable
array_cat(left: uuid[], right: uuid[]) → uuid[]

Appends two arrays.

+		Immutable
array_cat(left: anyenum[], right: anyenum[]) → anyenum[]

Appends two arrays.

+		Immutable
array_cat(left: box2d[], right: box2d[]) → box2d[]

Appends two arrays.

+		Immutable
array_cat(left: geography[], right: geography[]) → geography[]

Appends two arrays.

+		Immutable
array_cat(left: geometry[], right: geometry[]) → geometry[]

Appends two arrays.

+		Immutable
array_cat(left: jsonb[], right: jsonb[]) → jsonb[]

Appends two arrays.

+		Immutable
array_cat(left: ltree[], right: ltree[]) → ltree[]

Appends two arrays.

+		Immutable
array_cat(left: oid[], right: oid[]) → oid[]

Appends two arrays.

+		Immutable
array_cat(left: pg_lsn[], right: pg_lsn[]) → pg_lsn[]

Appends two arrays.

+		Immutable
array_cat(left: refcursor[], right: refcursor[]) → refcursor[]

Appends two arrays.

+		Immutable
array_cat(left: timetz[], right: timetz[]) → timetz[]

Appends two arrays.

+		Immutable
array_cat(left: tuple[], right: tuple[]) → tuple[]

Appends two arrays.

+		Immutable
array_cat(left: varbit[], right: varbit[]) → varbit[]

Appends two arrays.

+		Immutable
array_length(input: anyelement[], array_dimension: int) → int

Calculates the length of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_lower(input: anyelement[], array_dimension: int) → int

Calculates the minimum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_position(array: bool[], elem: bool) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bool[], elem: bool, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: bytes[], elem: bytes) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bytes[], elem: bytes, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: date[], elem: date) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: date[], elem: date, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: decimal[], elem: decimal) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: decimal[], elem: decimal, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: float[], elem: float) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: float[], elem: float, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: inet[], elem: inet) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: inet[], elem: inet, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: int[], elem: int) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: int[], elem: int, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: interval[], elem: interval) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: interval[], elem: interval, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: string[], elem: string) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: string[], elem: string, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: time[], elem: time) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: time[], elem: time, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timestamp[], elem: timestamp) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamp[], elem: timestamp, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: uuid[], elem: uuid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: uuid[], elem: uuid, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: anyenum[], elem: anyenum) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: anyenum[], elem: anyenum, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: box2d[], elem: box2d) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: box2d[], elem: box2d, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: geography[], elem: geography) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geography[], elem: geography, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: geometry[], elem: geometry) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geometry[], elem: geometry, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: jsonb[], elem: jsonb) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: jsonb[], elem: jsonb, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: ltree[], elem: ltree) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: ltree[], elem: ltree, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: oid[], elem: oid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: oid[], elem: oid, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: refcursor[], elem: refcursor) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: refcursor[], elem: refcursor, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timetz[], elem: timetz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timetz[], elem: timetz, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: tuple[], elem: tuple) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: tuple[], elem: tuple, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: varbit[], elem: varbit) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: varbit[], elem: varbit, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_positions(array: bool[], elem: bool) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: bytes[], elem: bytes) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: date[], elem: date) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: decimal[], elem: decimal) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: float[], elem: float) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: inet[], elem: inet) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: int[], elem: int) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: interval[], elem: interval) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: string[], elem: string) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: time[], elem: time) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamp[], elem: timestamp) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamptz[], elem: timestamptz) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: uuid[], elem: uuid) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: anyenum[], elem: anyenum) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: box2d[], elem: box2d) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geography[], elem: geography) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geometry[], elem: geometry) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: jsonb[], elem: jsonb) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: ltree[], elem: ltree) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: oid[], elem: oid) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: pg_lsn[], elem: pg_lsn) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: refcursor[], elem: refcursor) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timetz[], elem: timetz) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: tuple[], elem: tuple) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: varbit[], elem: varbit) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_prepend(elem: bool, array: bool[]) → bool[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: bytes, array: bytes[]) → bytes[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: date, array: date[]) → date[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: decimal, array: decimal[]) → decimal[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: float, array: float[]) → float[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: inet, array: inet[]) → inet[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: int, array: int[]) → int[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: interval, array: interval[]) → interval[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: string, array: string[]) → string[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: time, array: time[]) → time[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamp, array: timestamp[]) → timestamp[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamptz, array: timestamptz[]) → timestamptz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: uuid, array: uuid[]) → uuid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: anyenum, array: anyenum[]) → anyenum[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: box2d, array: box2d[]) → box2d[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geography, array: geography[]) → geography[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geometry, array: geometry[]) → geometry[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: jsonb, array: jsonb[]) → jsonb[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: ltree, array: ltree[]) → ltree[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: oid, array: oid[]) → oid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: pg_lsn, array: pg_lsn[]) → pg_lsn[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: refcursor, array: refcursor[]) → refcursor[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timetz, array: timetz[]) → timetz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: tuple, array: tuple[]) → tuple[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: varbit, array: varbit[]) → varbit[]

Prepends elem to array, returning the result.

+		Immutable
array_remove(array: bool[], elem: bool) → bool[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: bytes[], elem: bytes) → bytes[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: date[], elem: date) → date[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: decimal[], elem: decimal) → decimal[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: float[], elem: float) → float[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: inet[], elem: inet) → inet[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: int[], elem: int) → int[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: interval[], elem: interval) → interval[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: string[], elem: string) → string[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: time[], elem: time) → time[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamp[], elem: timestamp) → timestamp[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamptz[], elem: timestamptz) → timestamptz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: uuid[], elem: uuid) → uuid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: anyenum[], elem: anyenum) → anyenum[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: box2d[], elem: box2d) → box2d[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geography[], elem: geography) → geography[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geometry[], elem: geometry) → geometry[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: jsonb[], elem: jsonb) → jsonb[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: ltree[], elem: ltree) → ltree[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: oid[], elem: oid) → oid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: refcursor[], elem: refcursor) → refcursor[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timetz[], elem: timetz) → timetz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: tuple[], elem: tuple) → tuple[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: varbit[], elem: varbit) → varbit[]

Remove from array all elements equal to elem.

+		Immutable
array_replace(array: bool[], toreplace: bool, replacewith: bool) → bool[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: bytes[], toreplace: bytes, replacewith: bytes) → bytes[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: date[], toreplace: date, replacewith: date) → date[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: decimal[], toreplace: decimal, replacewith: decimal) → decimal[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: float[], toreplace: float, replacewith: float) → float[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: inet[], toreplace: inet, replacewith: inet) → inet[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: int[], toreplace: int, replacewith: int) → int[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: interval[], toreplace: interval, replacewith: interval) → interval[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: string[], toreplace: string, replacewith: string) → string[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: time[], toreplace: time, replacewith: time) → time[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamp[], toreplace: timestamp, replacewith: timestamp) → timestamp[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamptz[], toreplace: timestamptz, replacewith: timestamptz) → timestamptz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: uuid[], toreplace: uuid, replacewith: uuid) → uuid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: anyenum[], toreplace: anyenum, replacewith: anyenum) → anyenum[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: box2d[], toreplace: box2d, replacewith: box2d) → box2d[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geography[], toreplace: geography, replacewith: geography) → geography[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geometry[], toreplace: geometry, replacewith: geometry) → geometry[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: jsonb[], toreplace: jsonb, replacewith: jsonb) → jsonb[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: ltree[], toreplace: ltree, replacewith: ltree) → ltree[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: oid[], toreplace: oid, replacewith: oid) → oid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: pg_lsn[], toreplace: pg_lsn, replacewith: pg_lsn) → pg_lsn[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: refcursor[], toreplace: refcursor, replacewith: refcursor) → refcursor[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timetz[], toreplace: timetz, replacewith: timetz) → timetz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: tuple[], toreplace: tuple, replacewith: tuple) → tuple[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: varbit[], toreplace: varbit, replacewith: varbit) → varbit[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_to_string(input: anyelement[], delim: string) → string

Join an array into a string with a delimiter.

+		Stable
array_to_string(input: anyelement[], delimiter: string, null: string) → string

Join an array into a string with a delimiter, replacing NULLs with a null string.

+		Stable
array_upper(input: anyelement[], array_dimension: int) → int

Calculates the maximum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
cardinality(input: anyelement[]) → int

Calculates the number of elements contained in input

+		Immutable
jsonb_array_to_string_array(input: jsonb) → string[]

Convert a JSONB array into a string array.

+		Immutable
string_to_array(str: string, delimiter: string) → string[]

Split a string into components on a delimiter.

+		Immutable
string_to_array(str: string, delimiter: string, null: string) → string[]

Split a string into components on a delimiter with a specified string to consider NULL.

+		Immutable
+ +### BOOL functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Matches case insensetively unescaped with pattern using escape as an escape token.

+		Immutable
inet_contained_by_or_equals(val: inet, container: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_contains_or_equals(container: inet, val: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_same_family(val: inet, val: inet) → bool

Checks if two IP addresses are of the same IP family.

+		Immutable
like_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
not_ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches case insensetively with pattern using escape as an escape token.

+		Immutable
not_like_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
not_similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
+ +### Comparison functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
greatest(anyelement...) → anyelement

Returns the element with the greatest value.

+		Immutable
least(anyelement...) → anyelement

Returns the element with the lowest value.

+		Immutable
num_nonnulls(any...) → int

Returns the number of nonnull arguments.

+		Immutable
num_nulls(any...) → int

Returns the number of null arguments.

+		Immutable
+ +### Cryptographic functions + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crypt(password: string, salt: string) → string

Generates a hash based on a password and salt. The hash algorithm and number of rounds if applicable are encoded in the salt.

+		Immutable
decrypt(data: bytes, key: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
decrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
digest(data: bytes, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
digest(data: string, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
encrypt(data: bytes, key: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
encrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
gen_random_bytes(count: int) → bytes

Returns count cryptographically strong random bytes. At most 1024 bytes can be extracted at a time.

+		Volatile
gen_salt(type: string) → string

Generates a salt for input into the crypt function using the default number of rounds.

+		Volatile
gen_salt(type: string, iter_count: int) → string

Generates a salt for input into the crypt function using iter_count number of rounds.

+		Volatile
hmac(data: bytes, key: bytes, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
hmac(data: string, key: string, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
+ +### DECIMAL functions + + + + + +
Function → ReturnsDescriptionVolatility
hlc_to_timestamp(hlc: decimal) → timestamptz

Returns a TimestampTZ representation of a CockroachDB HLC in decimal form.

+

Note that a TimestampTZ has less precision than a CockroachDB HLC. It is intended as +a convenience function to display HLCs in a print-friendly form. Use the decimal +value if you rely on the HLC for accuracy.

+		Immutable
+ +### Date and time functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
age(end: timestamptz, begin: timestamptz) → interval

Calculates the interval between begin and end, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use the timestamptz subtraction operator.

+		Immutable
age(val: timestamptz) → interval

Calculates the interval between val and the current time, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use now() - timestamptz.

+		Stable
clock_timestamp() → timestamp

Returns the current system time on one of the cluster nodes.

+		Volatile
clock_timestamp() → timestamptz

Returns the current system time on one of the cluster nodes.

+		Volatile
current_date() → date

Returns the date of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_timestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
date_part(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
date_part(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
date_trunc(element: string, input: date) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: interval) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: time) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero.

+

Compatible elements: hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamp) → timestamp

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamptz) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: timestamptz, timezone: string) → timestamptz

Truncates input to precision element in the specified timezone. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
experimental_follower_read_timestamp() → timestamptz

Same as follower_read_timestamp. This name is deprecated.

+		Volatile
experimental_strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
extract(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
extract(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
extract_duration(element: string, input: interval) → int

Extracts element from input. +Compatible elements: hour, minute, second, millisecond, microsecond. +This is deprecated in favor of extract which supports duration.

+		Immutable
follower_read_timestamp() → timestamptz

Returns a timestamp which is very likely to be safe to perform +against a follower replica.

+

This function is intended to be used with an AS OF SYSTEM TIME clause to perform +historical reads against a time which is recent but sufficiently old for reads +to be performed against the closest replica as opposed to the currently +leaseholder for a given range.

+

Note that this function requires an enterprise license on a CCL distribution to +return a result that is less likely the closest replica. It is otherwise +hardcoded as -4.8s from the statement time, which may not result in reading from the +nearest replica.

+		Volatile
localtimestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
make_date(year: int, month: int, day: int) → date

Create date (formatted according to ISO 8601) from year, month, and day fields (negative years signify BC).

+		Immutable
make_timestamp(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamp

Create timestamp (formatted according to ISO 8601) from year, month, day, hour, minute, and seconds fields (negative years signify BC).

+		Immutable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float, timezone: string) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
now() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
overlaps(s1: date, e1: date, s1: date, e2: date) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: date, e1: interval, s1: date, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: interval, s1: time, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: time, s1: time, e2: time) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: interval, s1: timestamp, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: timestamp, s1: timestamp, e2: timestamp) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamptz, e1: interval, s1: timestamptz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Stable
overlaps(s1: timestamptz, e1: timestamptz, s1: timestamptz, e2: timestamptz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: interval, s1: timetz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: timetz, s1: timetz, e2: timetz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
statement_timestamp() → timestamp

Returns the start time of the current statement.

+		Stable
statement_timestamp() → timestamptz

Returns the start time of the current statement.

+		Stable
strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
timeofday() → string

Returns the current system time on one of the cluster nodes as a string.

+		Stable
timezone(timezone: string, time: time) → timetz

Treat given time without time zone as located in the specified time zone.

+		Stable
timezone(timezone: string, timestamp: timestamp) → timestamptz

Treat given time stamp without time zone as located in the specified time zone.

+		Immutable
timezone(timezone: string, timestamptz: timestamptz) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Immutable
timezone(timezone: string, timestamptz_string: string) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Stable
timezone(timezone: string, timetz: timetz) → timetz

Convert given time with time zone to the new time zone.

+		Stable
to_char(date: date) → string

Convert an date to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(date: date, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_char(interval: interval) → string

Convert an interval to a string assuming the Postgres IntervalStyle.

+		Immutable
to_char(interval: interval, format: string) → string

Convert an interval to a string using the given format.

+		Stable
to_char(timestamp: timestamp) → string

Convert an timestamp to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(timestamp: timestamp, format: string) → string

Convert an timestamp to a string using the given format.

+		Stable
to_char(timestamptz: timestamptz, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_timestamp(timestamp: float) → timestamptz

Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to timestamp with time zone.

+		Immutable
transaction_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
with_max_staleness(max_staleness: interval) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_max_staleness(max_staleness: interval, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
+ +### Enum functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
enum_first(val: anyenum) → anyenum

Returns the first value of the input enum type.

+		Stable
enum_last(val: anyenum) → anyenum

Returns the last value of the input enum type.

+		Stable
enum_range(lower: anyenum, upper: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array between the two arguments (inclusive).

+		Stable
enum_range(val: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array.

+		Stable
+ +### FLOAT functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abs(val: decimal) → decimal

Calculates the absolute value of val.

+		Immutable
abs(val: float) → float

Calculates the absolute value of val.

+		Immutable
abs(val: int) → int

Calculates the absolute value of val.

+		Immutable
acos(val: float) → float

Calculates the inverse cosine of val.

+		Immutable
acosd(val: float) → float

Calculates the inverse cosine of val with the result in degrees

+		Immutable
acosh(val: float) → float

Calculates the inverse hyperbolic cosine of val.

+		Immutable
asin(val: float) → float

Calculates the inverse sine of val.

+		Immutable
asind(val: float) → float

Calculates the inverse sine of val with the result in degrees.

+		Immutable
asinh(val: float) → float

Calculates the inverse hyperbolic sine of val.

+		Immutable
atan(val: float) → float

Calculates the inverse tangent of val.

+		Immutable
atan2(x: float, y: float) → float

Calculates the inverse tangent of x/y.

+		Immutable
atan2d(x: float, y: float) → float

Calculates the inverse tangent of x/y with the result in degrees

+		Immutable
atand(val: float) → float

Calculates the inverse tangent of val with the result in degrees.

+		Immutable
atanh(val: float) → float

Calculates the inverse hyperbolic tangent of val.

+		Immutable
cbrt(val: decimal) → decimal

Calculates the cube root (∛) of val.

+		Immutable
cbrt(val: float) → float

Calculates the cube root (∛) of val.

+		Immutable
ceil(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
cos(val: float) → float

Calculates the cosine of val.

+		Immutable
cosd(val: float) → float

Calculates the cosine of val where val is in degrees.

+		Immutable
cosh(val: float) → float

Calculates the hyperbolic cosine of val.

+		Immutable
cot(val: float) → float

Calculates the cotangent of val.

+		Immutable
cotd(val: float) → float

Calculates the cotangent of val where val is in degrees.

+		Immutable
degrees(val: float) → float

Converts val as a radian value to a degree value.

+		Immutable
div(x: decimal, y: decimal) → decimal

Calculates the integer quotient of x/y.

+		Immutable
div(x: float, y: float) → float

Calculates the integer quotient of x/y.

+		Immutable
div(x: int, y: int) → int

Calculates the integer quotient of x/y.

+		Immutable
exp(val: decimal) → decimal

Calculates e ^ val.

+		Immutable
exp(val: float) → float

Calculates e ^ val.

+		Immutable
floor(val: decimal) → decimal

Calculates the largest integer not greater than val.

+		Immutable
floor(val: float) → float

Calculates the largest integer not greater than val.

+		Immutable
floor(val: int) → float

Calculates the largest integer not greater than val.

+		Immutable
isnan(val: decimal) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
isnan(val: float) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
ln(val: decimal) → decimal

Calculates the natural log of val.

+		Immutable
ln(val: float) → float

Calculates the natural log of val.

+		Immutable
log(b: decimal, x: decimal) → decimal

Calculates the base b log of val.

+		Immutable
log(b: float, x: float) → float

Calculates the base b log of val.

+		Immutable
log(val: decimal) → decimal

Calculates the base 10 log of val.

+		Immutable
log(val: float) → float

Calculates the base 10 log of val.

+		Immutable
mod(x: decimal, y: decimal) → decimal

Calculates x%y.

+		Immutable
mod(x: float, y: float) → float

Calculates x%y.

+		Immutable
mod(x: int, y: int) → int

Calculates x%y.

+		Immutable
pi() → float

Returns the value for pi (3.141592653589793).

+		Immutable
pow(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
pow(x: float, y: float) → float

Calculates x^y.

+		Immutable
pow(x: int, y: int) → int

Calculates x^y.

+		Immutable
power(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
power(x: float, y: float) → float

Calculates x^y.

+		Immutable
power(x: int, y: int) → int

Calculates x^y.

+		Immutable
radians(val: float) → float

Converts val as a degree value to a radians value.

+		Immutable
random() → float

Returns a random floating-point number between 0 (inclusive) and 1 (exclusive). Note that the value contains at most 53 bits of randomness.

+		Volatile
round(input: decimal, decimal_accuracy: int) → decimal

Keeps decimal_accuracy number of figures to the right of the zero position in input using half away from zero rounding. If decimal_accuracy is not in the range -2^31…(2^31-1), the results are undefined.

+		Immutable
round(input: float, decimal_accuracy: int) → float

Keeps decimal_accuracy number of figures to the right of the zero position in input using half to even (banker’s) rounding.

+		Immutable
round(val: decimal) → decimal

Rounds val to the nearest integer, half away from zero: round(+/-2.4) = +/-2, round(+/-2.5) = +/-3.

+		Immutable
round(val: float) → float

Rounds val to the nearest integer using half to even (banker’s) rounding.

+		Immutable
setseed(seed: float) → void

Sets the seed for subsequent random() calls in this session (value between -1.0 and 1.0, inclusive). There are no guarantees as to how this affects the seed of random() calls that appear in the same query as setseed().

+		Volatile
sign(val: decimal) → decimal

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: float) → float

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: int) → int

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sin(val: float) → float

Calculates the sine of val.

+		Immutable
sind(val: float) → float

Calculates the sine of val where val is in degrees.

+		Immutable
sinh(val: float) → float

Calculates the hyperbolic sine of val.

+		Immutable
sqrt(val: decimal) → decimal

Calculates the square root of val.

+		Immutable
sqrt(val: float) → float

Calculates the square root of val.

+		Immutable
tan(val: float) → float

Calculates the tangent of val.

+		Immutable
tand(val: float) → float

Calculates the tangent of val where val is in degrees.

+		Immutable
tanh(val: float) → float

Calculates the hyperbolic tangent of val.

+		Immutable
trunc(val: decimal) → decimal

Truncates the decimal values of val.

+		Immutable
trunc(val: decimal, scale: int) → decimal

Truncate val to scale decimal places

+		Immutable
trunc(val: float) → float

Truncates the decimal values of val.

+		Immutable
+ +### Full Text Search functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
phraseto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The <-> operator is inserted between each token in the input.

+		Immutable
phraseto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The <-> operator is inserted between each token in the input.

+		Stable
plainto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The & operator is inserted between each token in the input.

+		Immutable
plainto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The & operator is inserted between each token in the input.

+		Stable
to_tsquery(config: string, text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the specified configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Immutable
to_tsquery(text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the default configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Stable
to_tsvector(config: string, text: string) → tsvector

Converts text to a tsvector, normalizing words according to the specified configuration. Position information is included in the result.

+		Immutable
to_tsvector(text: string) → tsvector

Converts text to a tsvector, normalizing words according to the default configuration. Position information is included in the result.

+		Stable
ts_parse(parser_name: string, document: string) → tuple{int AS tokid, string AS token}

ts_parse parses the given document and returns a series of records, one for each token produced by parsing. Each record includes a tokid showing the assigned token type and a token which is the text of the token.

+		Stable
ts_rank(vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
+ +### Fuzzy String Matching functions + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
levenshtein(source: string, target: string) → int

Calculates the Levenshtein distance between two strings. Maximum input length is 255 characters.

+		Immutable
levenshtein(source: string, target: string, ins_cost: int, del_cost: int, sub_cost: int) → int

Calculates the Levenshtein distance between two strings. The cost parameters specify how much to charge for each edit operation. Maximum input length is 255 characters.

+		Immutable
levenshtein_less_equal(source: string, target: string, ins_cost: int, del_cost: int, sub_cost: int, max_d: int) → int

Calculates the Levenshtein distance between two strings. The cost parameters specify how much to charge for each edit operation. If actual distance is less or equal then max_d, then it returns the distance. Otherwise this function returns a value greater than max_d. The maximum length of the input strings is 255 characters.

+		Immutable
levenshtein_less_equal(source: string, target: string, max_d: int) → int

Calculates the Levenshtein distance between two strings. If actual distance is less or equal then max_d, then it returns the distance. Otherwise this function returns a value greater than max_d. The maximum length of the input strings is 255 characters.

+		Immutable
metaphone(source: string, max_output_length: int) → string

Convert a string to its Metaphone code. Maximum input length is 255 characters

+		Immutable
soundex(source: string) → string

Convert a string to its Soundex code.

+		Immutable
+ +### ID generation functions + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
experimental_uuid_v4() → bytes

Returns a UUID.

+		Volatile
gen_random_ulid() → uuid

Generates a random ULID and returns it as a value of UUID type.

+		Volatile
gen_random_uuid() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
unique_rowid() → int

Returns a unique ID used by CockroachDB to generate unique row IDs if a Primary Key isn’t defined for the table. The value is a combination of the insert timestamp and the ID of the node executing the statement, which guarantees this combination is globally unique. However, there can be gaps and the order is not completely guaranteed.

+		Volatile
unordered_unique_rowid() → int

Returns a unique ID. The value is a combination of the insert timestamp (bit-reversed) and the ID of the node executing the statement, which guarantees this combination is globally unique. The way it is generated is statistically likely to not have any ordering relative to previously generated values.

+		Volatile
uuid_generate_v1() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. To avoid exposing the server’s real MAC address, this uses a random MAC address and a timestamp. Essentially, this is an alias for uuid_generate_v1mc.

+		Volatile
uuid_generate_v1mc() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. This uses a random MAC address and a timestamp.

+		Volatile
uuid_generate_v3(namespace: uuid, name: string) → uuid

Generates a version 3 UUID in the given namespace using the specified input name, with md5 as the hashing method. The namespace should be one of the special constants produced by the uuid_ns_*() functions.

+		Immutable
uuid_generate_v4() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
uuid_generate_v5(namespace: uuid, name: string) → uuid

Generates a version 5 UUID in the given namespace using the specified input name. This is similar to a version 3 UUID, except it uses SHA-1 for hashing.

+		Immutable
uuid_nil() → uuid

Returns a nil UUID constant.

+		Immutable
uuid_ns_dns() → uuid

Returns a constant designating the DNS namespace for UUIDs.

+		Immutable
uuid_ns_oid() → uuid

Returns a constant designating the ISO object identifier (OID) namespace for UUIDs. These are unrelated to the OID type used internally in the database.

+		Immutable
uuid_ns_url() → uuid

Returns a constant designating the URL namespace for UUIDs.

+		Immutable
uuid_ns_x500() → uuid

Returns a constant designating the X.500 distinguished name (DN) namespace for UUIDs.

+		Immutable
uuid_v4() → bytes

Returns a UUID.

+		Volatile
+ +### INET functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abbrev(val: inet) → string

Converts the combined IP address and prefix length to an abbreviated display format as text.For INET types, this will omit the prefix length if it’s not the default (32 or IPv4, 128 for IPv6)

+

For example, abbrev('192.168.1.2/24') returns '192.168.1.2/24'

+		Immutable
broadcast(val: inet) → inet

Gets the broadcast address for the network address represented by the value.

+

For example, broadcast('192.168.1.2/24') returns '192.168.1.255/24'

+		Immutable
family(val: inet) → int

Extracts the IP family of the value; 4 for IPv4, 6 for IPv6.

+

For example, family('::1') returns 6

+		Immutable
host(val: inet) → string

Extracts the address part of the combined address/prefixlen value as text.

+

For example, host('192.168.1.2/16') returns '192.168.1.2'

+		Immutable
hostmask(val: inet) → inet

Creates an IP host mask corresponding to the prefix length in the value.

+

For example, hostmask('192.168.1.2/16') returns '0.0.255.255'

+		Immutable
masklen(val: inet) → int

Retrieves the prefix length stored in the value.

+

For example, masklen('192.168.1.2/16') returns 16

+		Immutable
netmask(val: inet) → inet

Creates an IP network mask corresponding to the prefix length in the value.

+

For example, netmask('192.168.1.2/16') returns '255.255.0.0'

+		Immutable
set_masklen(val: inet, prefixlen: int) → inet

Sets the prefix length of val to prefixlen.

+

For example, set_masklen('192.168.1.2', 16) returns '192.168.1.2/16'.

+		Immutable
+ +### INT functions + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crc32c(bytes...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32c(string...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32ieee(bytes...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
crc32ieee(string...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
fnv32(bytes...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32(string...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32a(bytes...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv32a(string...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64(bytes...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64(string...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64a(bytes...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64a(string...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
width_bucket(operand: decimal, b1: decimal, b2: decimal, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2. Returns 0 or count+1 for an input outside that range.

+		Immutable
width_bucket(operand: int, b1: int, b2: int, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2.

+		Immutable
width_bucket(operand: anyelement, thresholds: anyelement[]) → int

return the bucket number to which operand would be assigned given an array listing the lower bounds of the buckets; returns 0 for an input less than the first lower bound; the thresholds array must be sorted, smallest first, or unexpected results will be obtained

+		Immutable
+ +### JSONB functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_to_json(array: anyelement[]) → jsonb

Returns the array as JSON or JSONB.

+		Stable
array_to_json(array: anyelement[], pretty_bool: bool) → jsonb

Returns the array as JSON or JSONB.

+		Stable
json_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
json_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
json_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
json_build_array(any...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
json_build_object(any...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
json_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
json_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
json_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
json_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
json_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
json_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
json_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
json_remove_path(val: jsonb, path: string[]) → jsonb

Remove the specified path from the JSON object.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
json_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
json_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
json_valid(string: string) → bool

Returns whether the given string is a valid JSON or not

+		Immutable
jsonb_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
jsonb_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
jsonb_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
jsonb_build_array(any...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
jsonb_build_object(any...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
jsonb_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
jsonb_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
jsonb_exists_any(json: jsonb, array: string[]) → bool

Returns whether any of the strings in the text array exist as top-level keys or array elements

+		Immutable
jsonb_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments. new_val will be inserted before path target.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb, insert_after: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If insert_after is true (default is false), new_val will be inserted after path target.

+		Immutable
jsonb_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
jsonb_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
jsonb_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
jsonb_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
jsonb_pretty(val: jsonb) → string

Returns the given JSON value as a STRING indented and with newlines.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
jsonb_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
jsonb_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
row_to_json(row: tuple) → jsonb

Returns the row as a JSON object.

+		Stable
to_json(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
to_jsonb(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
+ +### Jsonpath functions + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
jsonb_path_exists(target: jsonb, path: jsonpath) → bool

Checks whether the JSON path returns any item for the specified JSON value.

+		Immutable
jsonb_path_exists(target: jsonb, path: jsonpath, vars: jsonb) → bool

Checks whether the JSON path returns any item for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named +values to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_exists(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → bool

Checks whether the JSON path returns any item for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named +values to be substituted into the jsonpath expression. If the silent +argument is true, the function suppresses the following errors: +missing object field or array element, unexpected JSON item type, +datetime and numeric errors.

+		Immutable
jsonb_path_match(target: jsonb, path: jsonpath) → bool

Returns the SQL boolean result of a JSON path predicate check +for the specified JSON value. (This is useful only with predicate check +expressions, not SQL-standard JSON path expressions, since it will +either fail or return NULL if the path result is not a single boolean +value.)

+		Immutable
jsonb_path_match(target: jsonb, path: jsonpath, vars: jsonb) → bool

Returns the SQL boolean result of a JSON path predicate check +for the specified JSON value. (This is useful only with predicate check +expressions, not SQL-standard JSON path expressions, since it will +either fail or return NULL if the path result is not a single boolean +value.) The vars argument must be a JSON object, and its fields provide +named values to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_match(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → bool

Returns the SQL boolean result of a JSON path predicate check +for the specified JSON value. (This is useful only with predicate check +expressions, not SQL-standard JSON path expressions, since it will +either fail or return NULL if the path result is not a single boolean +value.) The vars argument must be a JSON object, and its fields provide +named values to be substituted into the jsonpath expression. If the +silent argument is true, the function suppresses the following errors: +missing object field or array element, unexpected JSON item type, +datetime and numeric errors.

+		Immutable
jsonb_path_query(target: jsonb, path: jsonpath) → jsonb

Returns all JSON items returned by the JSON path for the specified JSON value.

+		Immutable
jsonb_path_query(target: jsonb, path: jsonpath, vars: jsonb) → jsonb

Returns all JSON items returned by the JSON path for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_query(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → jsonb

Returns all JSON items returned by the JSON path for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression. If the silent argument is true, +the function suppresses the following errors: missing object field or array +element, unexpected JSON item type, datetime and numeric errors.

+		Immutable
jsonb_path_query_array(target: jsonb, path: jsonpath) → jsonb

Returns all JSON items returned by the JSON path for the +specified JSON value, as a JSON array.

+		Immutable
jsonb_path_query_array(target: jsonb, path: jsonpath, vars: jsonb) → jsonb

Returns all JSON items returned by the JSON path for the +specified JSON value, as a JSON array. The vars argument must be a +JSON object, and its fields provide named values to be substituted +into the jsonpath expression.

+		Immutable
jsonb_path_query_array(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → jsonb

Returns all JSON items returned by the JSON path for the +specified JSON value, as a JSON array. The vars argument must be a +JSON object, and its fields provide named values to be substituted +into the jsonpath expression. If the silent argument is true, the +function suppresses the following errors: missing object field or +array element, unexpected JSON item type, datetime and numeric errors.

+		Immutable
jsonb_path_query_first(target: jsonb, path: jsonpath) → jsonb

Returns the first JSON item returned by the JSON path for the +specified JSON value, or NULL if there are no results.

+		Immutable
jsonb_path_query_first(target: jsonb, path: jsonpath, vars: jsonb) → jsonb

Returns the first JSON item returned by the JSON path for the +specified JSON value, or NULL if there are no results. The vars +argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_query_first(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → jsonb

Returns the first JSON item returned by the JSON path for the +specified JSON value, or NULL if there are no results. The vars +argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression. If the silent argument is true, the +function suppresses the following errors: missing object field or +array element, unexpected JSON item type, datetime and numeric errors.

+		Immutable
+ +### LTree functions + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
index(a: ltree, b: ltree) → int

position of first occurrence of b in a; -1 if not found

+		Immutable
index(a: ltree, b: ltree, offset: int) → int

position of first occurrence of b in a, starting at offset; -1 if not found

+		Immutable
lca(ltree, ltree, ltree...) → ltree

lowest common ancestor, i.e., longest common prefix of paths

+		Immutable
lca(ltree[]: ltree[]) → ltree

lowest common ancestor, i.e., longest common prefix of paths

+		Immutable
ltree2text(ltree: ltree) → string

cast ltree to text

+		Immutable
nlevel(ltree: ltree) → int

number of labels in path ltree

+		Immutable
subltree(ltree: ltree, start: int, end: int) → ltree

subpath of ltree from position start to position end-1 (counting from 0)

+		Immutable
subpath(ltree: ltree, offset: int) → ltree

subpath of ltree starting at position offset, extending to end of path. If offset is negative, subpath starts that far from the end of the path.

+		Immutable
subpath(ltree: ltree, offset: int, length: int) → ltree

subpath of ltree starting at position offset, length length. If offset is negative, subpath starts that far from the end of the path. If length is negative, leaves that many labels off the end of the path.

+		Immutable
text2ltree(text: string) → ltree

cast text to ltree

+		Immutable
+ +### Multi-region functions + + + + + + + +
Function → ReturnsDescriptionVolatility
default_to_database_primary_region(val: string) → string

Returns the given region if the region has been added to the current database. +Otherwise, this will return the primary region of the current database. +This will error if the current database is not a multi-region database.

+		Stable
gateway_region() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
rehome_row() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
+ +### PGVector functions + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cosine_distance(v1: vector, v2: vector) → float

Returns the cosine distance between the two vectors.

+		Immutable
inner_product(v1: vector, v2: vector) → float

Returns the inner product between the two vectors.

+		Immutable
l1_distance(v1: vector, v2: vector) → float

Returns the Manhattan distance between the two vectors.

+		Immutable
l2_distance(v1: vector, v2: vector) → float

Returns the Euclidean distance between the two vectors.

+		Immutable
vector_dims(vector: vector) → int

Returns the number of the dimensions in the vector.

+		Immutable
vector_norm(vector: vector) → float

Returns the Euclidean norm of the vector.

+		Immutable
+ +### STRING[] functions + + + + + + +
Function → ReturnsDescriptionVolatility
regexp_split_to_array(string: string, pattern: string) → string[]

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_array(string: string, pattern: string, flags: string) → string[]

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
+ +### Sequence functions + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
currval(sequence_name: string) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
currval(sequence_name: regclass) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
lastval() → int

Return value most recently obtained with nextval in this session.

+		Volatile
nextval(sequence_name: string) → int

Advances the given sequence and returns its new value.

+		Volatile
nextval(sequence_name: regclass) → int

Advances the given sequence and returns its new value.

+		Volatile
setval(sequence_name: string, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: string, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
setval(sequence_name: regclass, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: regclass, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
+ +### Set-returning functions + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
aclexplode(aclitems: string[]) → tuple{oid AS grantor, oid AS grantee, string AS privilege_type, bool AS is_grantable}

Produces a virtual table containing aclitem stuff (returns no rows as this feature is unsupported in CockroachDB)

+		Stable
generate_series(start: int, end: int) → int

Produces a virtual table containing the integer values from start to end, inclusive.

+		Immutable
generate_series(start: int, end: int, step: int) → int

Produces a virtual table containing the integer values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamp, end: timestamp, step: interval) → timestamp

Produces a virtual table containing the timestamp values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamptz, end: timestamptz, step: interval) → timestamptz

Produces a virtual table containing the timestampTZ values from start to end, inclusive, by increment of step.

+		Immutable
generate_subscripts(array: anyelement[]) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int, reverse: bool) → int

Returns a series comprising the given array’s subscripts.

+

When reverse is true, the series is returned in reverse order.

+		Immutable
information_schema._pg_expandarray(input: anyelement[]) → tuple{anyelement AS x, int AS n}

Returns the input array as a set of rows with an index

+		Immutable
json_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
json_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
json_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
jsonb_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
jsonb_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
jsonb_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
pg_get_keywords() → tuple{string AS word, string AS catcode, string AS catdesc}

Produces a virtual table containing the keywords known to the SQL parser.

+		Immutable
pg_options_to_table(options: string[]) → tuple{string AS option_name, string AS option_value}

Converts the options array format to a table.

+		Stable
regexp_split_to_table(string: string, pattern: string) → string

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_table(string: string, pattern: string, flags: string) → string

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
unnest(anyelement[], anyelement[], anyelement[]...) → tuple{anyelement AS unnest, anyelement AS unnest, anyelement AS unnest}

Returns the input arrays as a set of rows

+		Immutable
unnest(input: anyelement[]) → anyelement

Returns the input array as a set of rows

+		Immutable
workload_index_recs() → tuple{string AS index_rec, bytes[] AS fingerprint_ids}

Returns index recommendations and the fingerprint ids that the indexes will impact

+		Immutable
workload_index_recs(timestamptz: timestamptz) → tuple{string AS index_rec, bytes[] AS fingerprint_ids}

Returns index recommendations and the fingerprint ids that the indexes will impact

+		Immutable
+ +### Spatial functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
_st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
geometrytype(geometry: geometry) → string

Returns the type of geometry as a string.

+

This function utilizes the GEOS module.

+		Immutable
geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
postgis_addbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_dropbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_extensions_upgrade() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_full_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_geos_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_getbbox(geometry: geometry) → box2d

Returns a box2d encapsulating the given Geometry.

+		Immutable
postgis_hasbbox(geometry: geometry) → bool

Returns whether a given Geometry has a bounding box. False for points and empty geometries; always true otherwise.

+		Immutable
postgis_lib_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_lib_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_liblwgeom_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_libxml_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_proj_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_installed() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_released() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_wagyu_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
st_3dlength(geometry: geometry) → float

Returns the 3-dimensional or 2-dimensional length of the geometry.

+

Note ST_3DLength is only valid for LineString or MultiLineString. +For 2-D lines it will return the 2-D length (same as ST_Length and ST_Length2D)

+

This function utilizes the GEOS module.

+		Immutable
st_addmeasure(geometry: geometry, start: float, end: float) → geometry

Returns a copy of a LineString or MultiLineString with measure coordinates linearly interpolated between the specified start and end values. Any existing M coordinates will be overwritten.

+		Immutable
st_addpoint(line_string: geometry, point: geometry) → geometry

Adds a Point to the end of a LineString.

+		Immutable
st_addpoint(line_string: geometry, point: geometry, index: int) → geometry

Adds a Point to a LineString at the given 0-based index (-1 to append).

+		Immutable
st_affine(geometry: geometry, a: float, b: float, c: float, d: float, e: float, f: float, g: float, h: float, i: float, x_off: float, y_off: float, z_off: float) → geometry

Applies a 3D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b c x_off \ / x
+| d e f y_off | | y | +| g h i z_off | | z | +\ 0 0 0 1 / \ 0 /

+		Immutable
st_affine(geometry: geometry, a: float, b: float, d: float, e: float, x_off: float, y_off: float) → geometry

Applies a 2D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b x_off \ / x
+| d e y_off | | y | +\ 0 0 1 / \ 0 /

+		Immutable
st_angle(line1: geometry, line2: geometry) → float

Returns the clockwise angle between two LINESTRING geometries, treating them as vectors between their start- and endpoints. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry) → float

Returns the clockwise angle between the vectors formed by point2,point1 and point2,point3. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry, point4: geometry) → float

Returns the clockwise angle between the vectors formed by point1,point2 and point3,point4. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_area(geography: geography) → float

Returns the area of the given geography in meters^2. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geography: geography, use_spheroid: bool) → float

Returns the area of the given geography in meters^2.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_area(geometry_str: string) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_area2d(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_asbinary(geography: geography) → bytes

Returns the WKB representation of a given Geography.

+		Immutable
st_asbinary(geography: geography, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asbinary(geometry: geometry) → bytes

Returns the WKB representation of a given Geometry.

+		Immutable
st_asbinary(geometry: geometry, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asencodedpolyline(geometry: geometry) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Preserves 5 decimal places.

+		Immutable
st_asencodedpolyline(geometry: geometry, precision: int4) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+		Immutable
st_asewkb(geography: geography) → bytes

Returns the EWKB representation of a given Geography.

+		Immutable
st_asewkb(geometry: geometry) → bytes

Returns the EWKB representation of a given Geometry.

+		Immutable
st_asewkt(geography: geography) → string

Returns the EWKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_asewkt(geography: geography, max_decimal_digits: int) → string

Returns the EWKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry: geometry) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_asewkt(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry_str: string) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asewkt(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geography: geography) → string

Returns the GeoJSON representation of a given Geography. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option (default for Geography)
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326
    • +
+		Immutable
st_asgeojson(geometry: geometry) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+		Immutable
st_asgeojson(geometry_str: string) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(row: tuple) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(row: tuple, geo_column: string) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. Coordinates have a maximum of 9 decimal digits.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int, pretty: bool) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value. Output will be pretty printed in JSON if pretty is true.

+		Stable
st_ashexewkb(geography: geography) → string

Returns the EWKB representation in hex of a given Geography.

+		Immutable
st_ashexewkb(geography: geography, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexewkb(geometry: geometry) → string

Returns the EWKB representation in hex of a given Geometry.

+		Immutable
st_ashexewkb(geometry: geometry, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexwkb(geography: geography) → string

Returns the WKB representation in hex of a given Geography.

+		Immutable
st_ashexwkb(geometry: geometry) → string

Returns the WKB representation in hex of a given Geometry.

+		Immutable
st_askml(geography: geography) → string

Returns the KML representation of a given Geography.

+		Immutable
st_askml(geometry: geometry) → string

Returns the KML representation of a given Geometry.

+		Immutable
st_askml(geometry_str: string) → string

Returns the KML representation of a given Geometry.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping. +Uses 4096 as the tile extent size in tile coordinate space.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int, clip: bool) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds if required.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry can be transformed, and clipped if required.

+		Immutable
st_astext(geography: geography) → string

Returns the WKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_astext(geography: geography, max_decimal_digits: int) → string

Returns the WKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry: geometry) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_astext(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry_str: string) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astext(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int, precision_m: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_azimuth(geography_a: geography, geography_b: geography) → float

Returns the azimuth in radians of the segment defined by the given point geographies, or NULL if the two points are coincident. It is solved using the Inverse geodesic problem.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_azimuth(geometry_a: geometry, geometry_b: geometry) → float

Returns the azimuth in radians of the segment defined by the given point geometries, or NULL if the two points are coincident.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+		Immutable
st_bdpolyfromtext(str: string, srid: int) → geometry

Returns a Polygon from multilinestring WKT with a SRID. If the input is not a multilinestring an error will be thrown.

+		Immutable
st_boundary(geometry: geometry) → geometry

Returns the closure of the combinatorial boundary of this Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_box2dfromgeohash(geohash: string) → box2d

Return a Box2D from a GeoHash string with max precision.

+		Immutable
st_box2dfromgeohash(geohash: string, precision: int) → box2d

Return a Box2D from a GeoHash string with supplied precision.

+		Immutable
st_buffer(geography: geography, distance: float) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, buffer_style_params: string) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, quad_segs: int) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geometry: geometry, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry_str: string, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_centroid(geography: geography) → geography

Returns the centroid of given geography. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geography: geography, use_spheroid: bool) → geography

Returns the centroid of given geography.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geometry: geometry) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_centroid(geometry_str: string) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_clipbybox2d(geometry: geometry, box2d: box2d) → geometry

Clips the geometry to conform to the bounding box specified by box2d.

+		Immutable
st_closestpoint(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the 2-dimensional point on geometry_a that is closest to geometry_b. This is the first point of the shortest line.

+		Immutable
st_collectionextract(geometry: geometry, type: int) → geometry

Given a collection, returns a multitype consisting only of elements of the specified type. If there are no elements of the given type, an EMPTY geometry is returned. Types are specified as 1=POINT, 2=LINESTRING, 3=POLYGON - other types are not supported.

+		Immutable
st_collectionhomogenize(geometry: geometry) → geometry

Returns the “simplest” representation of a collection’s contents. Collections of a single type will be returned as an appopriate multitype, or a singleton if it only contains a single geometry.

+		Immutable
st_combinebbox(box2d: box2d, geometry: geometry) → box2d

Combines the current bounding box with the bounding box of the Geometry.

+		Immutable
st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_convexhull(geometry: geometry) → geometry

Returns a geometry that represents the Convex Hull of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_coorddim(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_difference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the difference of two Geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_dimension(geometry: geometry) → int

Returns the number of topological dimensions of a given Geometry.

+		Immutable
st_disjoint(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a does not overlap, touch or is within geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_distance(geography_a: geography, geography_b: geography) → float

Returns the distance in meters between geography_a and geography_b. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geography_a: geography, geography_b: geography, use_spheroid: bool) → float

Returns the distance in meters between geography_a and geography_b.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance between the given geometries.

+		Immutable
st_distance(geometry_a_str: string, geometry_b_str: string) → float

Returns the distance between the given geometries.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_distancesphere(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_distancespheroid(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a spheroid.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_endpoint(geometry: geometry) → geometry

Returns the last point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_envelope(box2d: box2d) → geometry

Returns a bounding geometry for the given box.

+		Immutable
st_envelope(geometry: geometry) → geometry

Returns a bounding envelope for the given geometry.

+

For geometries which have a POINT or LINESTRING bounding box (i.e. is a single point +or a horizontal or vertical line), a POINT or LINESTRING is returned. Otherwise, the +returned POLYGON will be ordered Bottom Left, Top Left, Top Right, Bottom Right, +Bottom Left.

+		Immutable
st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string, parent_only: bool) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+

The parent_only boolean is always ignored.

+		Stable
st_estimatedextent(table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_expand(box2d: box2d, delta: float) → box2d

Extends the box2d by delta units across all dimensions.

+		Immutable
st_expand(box2d: box2d, delta_x: float, delta_y: float) → box2d

Extends the box2d by delta_x units in the x dimension and delta_y units in the y dimension.

+		Immutable
st_expand(geometry: geometry, delta: float) → geometry

Extends the bounding box represented by the geometry by delta units across all dimensions, returning a Polygon representing the new bounding box.

+		Immutable
st_expand(geometry: geometry, delta_x: float, delta_y: float) → geometry

Extends the bounding box represented by the geometry by delta_x units in the x dimension and delta_y units in the y dimension, returning a Polygon representing the new bounding box.

+		Immutable
st_exteriorring(geometry: geometry) → geometry

Returns the exterior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon.

+		Immutable
st_flipcoordinates(geometry: geometry) → geometry

Returns a new geometry with the X and Y axes flipped.

+		Immutable
st_force2d(geometry: geometry) → geometry

Returns a Geometry that is forced into XY layout with any Z or M dimensions discarded.

+		Immutable
st_force3d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to 0. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry, defaultM: float) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to the specified default M value. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force4d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZM layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float, defaultM: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified Z value. If a M coordinate doesn’t exist, it will be set to the specified M value.

+		Immutable
st_forcecollection(geometry: geometry) → geometry

Converts the geometry into a GeometryCollection.

+		Immutable
st_forcepolygonccw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_forcepolygoncw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Frechet distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Frechet distance between the given geometries, with the given segment densification (range 0.0-1.0, -1 to disable).

+

Smaller densify_frac gives a more accurate Fréchet distance. However, the computation time and memory usage increases with the square of the number of subsegments.

+

This function utilizes the GEOS module.

+		Immutable
st_generatepoints(geometry: geometry, npoints: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. Uses system time as a seed. +The requested number of points must be not larger than 65336.

+		Volatile
st_generatepoints(geometry: geometry, npoints: int4, seed: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. +The requested number of points must be not larger than 65336.

+		Immutable
st_geogfromewkb(val: bytes) → geography

Returns the Geography from an EWKB representation.

+		Immutable
st_geogfromewkt(val: string) → geography

Returns the Geography from an EWKT representation.

+		Immutable
st_geogfromgeojson(val: string) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromgeojson(val: jsonb) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geogfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geogfromwkb(bytes: bytes, srid: int) → geography

Returns the Geography from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geogfromwkb(val: bytes) → geography

Returns the Geography from a WKB (or EWKB) representation.

+		Immutable
st_geographyfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geographyfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geohash(geography: geography) → string

Returns a GeoHash representation of the geeographywith full precision if a point is provided, or with variable precision based on the size of the feature.

+		Immutable
st_geohash(geography: geography, precision: int) → string

Returns a GeoHash representation of the geography with the supplied precision.

+		Immutable
st_geohash(geometry: geometry) → string

Returns a GeoHash representation of the geometry with full precision if a point is provided, or with variable precision based on the size of the feature. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geohash(geometry: geometry, precision: int) → string

Returns a GeoHash representation of the geometry with the supplied precision. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geomcollfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomcollfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geometryfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geometryfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geometryn(geometry: geometry, n: int) → geometry

Returns the n-th Geometry (1-indexed). Returns NULL if out of bounds.

+		Immutable
st_geometrytype(geometry: geometry) → string

Returns the type of geometry as a string prefixed with ST_.

+

This function utilizes the GEOS module.

+		Immutable
st_geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
st_geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
st_geomfromgeohash(geohash: string) → geometry

Return a POLYGON Geometry from a GeoHash string with max precision.

+		Immutable
st_geomfromgeohash(geohash: string, precision: int) → geometry

Return a POLYGON Geometry from a GeoHash string with supplied precision.

+		Immutable
st_geomfromgeojson(val: string) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromgeojson(val: jsonb) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geomfromwkb(bytes: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geomfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_hasarc(geometry: geometry) → bool

Returns whether there is a CIRCULARSTRING in the geometry.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Hausdorff distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Hausdorff distance between the given geometries, with the given segment densification (range 0.0-1.0).

+

This function utilizes the GEOS module.

+		Immutable
st_interiorringn(geometry: geometry, n: int) → geometry

Returns the n-th (1-indexed) interior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon, or the ring does not exist.

+		Immutable
st_intersection(geography_a: geography, geography_b: geography) → geography

Returns the point intersections of the given geographies.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a_str: string, geometry_b_str: string) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_isclosed(geometry: geometry) → bool

Returns whether the geometry is closed as defined by whether the start and end points are coincident. Points are considered closed, empty geometries are not. For collections and multi-types, all members must be closed, as must all polygon rings.

+		Immutable
st_iscollection(geometry: geometry) → bool

Returns whether the geometry is of a collection type (including multi-types).

+		Immutable
st_isempty(geometry: geometry) → bool

Returns whether the geometry is empty.

+		Immutable
st_ispolygonccw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are considered counter-clockwise.

+		Immutable
st_ispolygoncw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are considered clockwise.

+		Immutable
st_isring(geometry: geometry) → bool

Returns whether the geometry is a single linestring that is closed and simple, as defined by ST_IsClosed and ST_IsSimple.

+

This function utilizes the GEOS module.

+		Immutable
st_issimple(geometry: geometry) → bool

Returns true if the geometry has no anomalous geometric points, e.g. that it intersects with or lies tangent to itself.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry) → bool

Returns whether the geometry is valid as defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry, flags: int) → bool

Returns whether the geometry is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry) → string

Returns a string containing the reason the geometry is invalid along with the point of interest, or “Valid Geometry” if it is valid. Validity is defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry, flags: int) → string

Returns the reason the geometry is invalid or “Valid Geometry” if it is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidtrajectory(geometry: geometry) → bool

Returns whether the geometry encodes a valid trajectory.

+

Note the geometry must be a LineString with M coordinates.

+		Immutable
st_length(geography: geography) → float

Returns the length of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geography: geography, use_spheroid: bool) → float

Returns the length of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_length(geometry_str: string) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_length2d(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_linecrossingdirection(linestring_a: geometry, linestring_b: geometry) → int

Returns an interger value defining behavior of crossing of lines: +0: lines do not cross, +-1: linestring_b crosses linestring_a from right to left, +1: linestring_b crosses linestring_a from left to right, +-2: linestring_b crosses linestring_a multiple times from right to left, +2: linestring_b crosses linestring_a multiple times from left to right, +-3: linestring_b crosses linestring_a multiple times from left to left, +3: linestring_b crosses linestring_a multiple times from right to right.

+

Note that the top vertex of the segment touching another line does not count as a crossing, but the bottom vertex of segment touching another line is considered a crossing.

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string) → geometry

Creates a LineString from an Encoded Polyline string.

+

Returns valid results only if the polyline was encoded with 5 decimal places.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string, precision: int4) → geometry

Creates a LineString from an Encoded Polyline string.

+

Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefrommultipoint(geometry: geometry) → geometry

Creates a LineString from a MultiPoint geometry.

+		Immutable
st_linefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_lineinterpolatepoint(geometry: geometry, fraction: float) → geometry

Returns a point along the given LineString which is at given fraction of LineString’s total length.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float, repeat: bool) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length. If repeat is false (default true) then it returns first point.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_linelocatepoint(line: geometry, point: geometry) → float

Returns a float between 0 and 1 representing the location of the closest point on LineString to the given Point, as a fraction of total 2d line length.

+		Immutable
st_linemerge(geometry: geometry) → geometry

Returns a LineString or MultiLineString by joining together constituents of a MultiLineString with matching endpoints. If the input is not a MultiLineString or LineString, an empty GeometryCollection is returned.

+

This function utilizes the GEOS module.

+		Immutable
st_linestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: decimal, end_fraction: decimal) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: float, end_fraction: float) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_longestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the max distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the maximum distance between the geometry’s vertexes. The function will return the longest line that was discovered first when comparing maximum distances if more than one is found.

+		Immutable
st_m(geometry: geometry) → float

Returns the M coordinate of a geometry if it is a Point.

+		Immutable
st_makebox2d(geometry_a: geometry, geometry_b: geometry) → box2d

Creates a box2d from two points. Errors if arguments are not two non-empty points.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with SRID 0.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float, srid: int) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with the given SRID.

+		Immutable
st_makepoint(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float) → geometry

Returns a new Point with the given X, Y, and Z coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float, m: float) → geometry

Returns a new Point with the given X, Y, Z, and M coordinates.

+		Immutable
st_makepointm(x: float, y: float, m: float) → geometry

Returns a new Point with the given X, Y, and M coordinates.

+		Immutable
st_makepolygon(geometry: geometry) → geometry

Returns a new Polygon with the given outer LineString.

+		Immutable
st_makepolygon(outer: geometry, interior: anyelement[]) → geometry

Returns a new Polygon with the given outer LineString and interior (hole) LineString(s).

+		Immutable
st_makevalid(geometry: geometry) → geometry

Returns a valid form of the given geometry according to the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_maxdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the maximum distance across every pair of points comprising the given geometries. Note if the geometries are the same, it will return the maximum distance between the geometry’s vertexes.

+		Immutable
st_memsize(geometry: geometry) → int

Returns the amount of memory space (in bytes) the geometry takes.

+		Immutable
st_minimumboundingcircle(geometry: geometry) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingcircle(geometry: geometry, num_segs: int) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingradius(geometry: geometry) → tuple{geometry AS center, float AS radius}

Returns a record containing the center point and radius of the smallest circle that can fully contains the given geometry.

+		Immutable
st_minimumclearance(geometry: geometry) → float

Returns the minimum distance a vertex can move before producing an invalid geometry. Returns Infinity if no minimum clearance can be found (e.g. for a single point).

+		Immutable
st_minimumclearanceline(geometry: geometry) → geometry

Returns a LINESTRING spanning the minimum distance a vertex can move before producing an invalid geometry. If no minimum clearance can be found (e.g. for a single point), an empty LINESTRING is returned.

+		Immutable
st_mlinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mlinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mpointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multi(geometry: geometry) → geometry

Returns the geometry as a new multi-geometry, e.g converts a POINT to a MULTIPOINT. If the input is already a multitype or collection, it is returned as is.

+		Immutable
st_multilinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multipointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_ndims(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_node(geometry: geometry) → geometry

Adds a node on a geometry for each intersection. Resulting geometry is always a MultiLineString.

+		Immutable
st_normalize(geometry: geometry) → geometry

Returns the geometry in its normalized form.

+

This function utilizes the GEOS module.

+		Immutable
st_npoints(geometry: geometry) → int

Returns the number of points in a given Geometry. Works for any shape type.

+		Immutable
st_nrings(geometry: geometry) → int

Returns the number of rings in a Polygon Geometry. Returns 0 if the shape is not a Polygon.

+		Immutable
st_numgeometries(geometry: geometry) → int

Returns the number of shapes inside a given Geometry.

+		Immutable
st_numinteriorring(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numinteriorrings(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numpoints(geometry: geometry) → int

Returns the number of points in a LineString. Returns NULL if the Geometry is not a LineString.

+		Immutable
st_orderingequals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is exactly equal to geometry_b, having all coordinates in the same order, as well as the same type, SRID, bounding box, and so on.

+		Immutable
st_orientedenvelope(geometry: geometry) → geometry

Returns a minimum rotated rectangle enclosing a geometry. +Note that more than one minimum rotated rectangle may exist. +May return a Point or LineString in the case of degenerate inputs.

+		Immutable
st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_perimeter(geography: geography) → float

Returns the perimeter of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geography: geography, use_spheroid: bool) → float

Returns the perimeter of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_perimeter2d(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_point(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_pointfromgeohash(geohash: string) → geometry

Return a POINT Geometry from a GeoHash string with max precision.

+		Immutable
st_pointfromgeohash(geohash: string, precision: int) → geometry

Return a POINT Geometry from a GeoHash string with supplied precision.

+		Immutable
st_pointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Point, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_pointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointinsidecircle(geometry: geometry, x_coord: float, y_coord: float, radius: float) → bool

Returns the true if the geometry is a point and is inside the circle. Returns false otherwise.

+		Immutable
st_pointn(geometry: geometry, n: int) → geometry

Returns the n-th Point of a LineString (1-indexed). Returns NULL if out of bounds or not a LineString.

+		Immutable
st_pointonsurface(geometry: geometry) → geometry

Returns a point that intersects with the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_points(geometry: geometry) → geometry

Returns all coordinates in the given Geometry as a MultiPoint, including duplicates.

+		Immutable
st_polyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygon(geometry: geometry, srid: int) → geometry

Returns a new Polygon from the given LineString and sets its SRID. It is equivalent to ST_MakePolygon with a single argument followed by ST_SetSRID.

+		Immutable
st_polygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_project(geography: geography, distance: float, azimuth: float) → geography

Returns a point projected from a start point along a geodesic using a given distance and azimuth (bearing). +This is known as the direct geodesic problem.

+

The distance is given in meters. Negative values are supported.

+

The azimuth (also known as heading or bearing) is given in radians. It is measured clockwise from true north (azimuth zero). +East is azimuth π/2 (90 degrees); south is azimuth π (180 degrees); west is azimuth 3π/2 (270 degrees). +Negative azimuth values and values greater than 2π (360 degrees) are supported.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, bnr: int) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b using the given boundary node rule (1:OGC/MOD2, 2:Endpoint, 3:MultivalentEndpoint, 4:MonovalentEndpoint).

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, pattern: string) → bool

Returns whether the DE-9IM spatial relation between geometry_a and geometry_b matches the DE-9IM pattern.

+

This function utilizes the GEOS module.

+		Immutable
st_relatematch(intersection_matrix: string, pattern: string) → bool

Returns whether the given DE-9IM intersection matrix satisfies the given pattern.

+		Immutable
st_removepoint(line_string: geometry, index: int) → geometry

Removes the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_removerepeatedpoints(geometry: geometry) → geometry

Returns a geometry with repeated points removed.

+		Immutable
st_removerepeatedpoints(geometry: geometry, tolerance: float) → geometry

Returns a geometry with repeated points removed, within the given distance tolerance.

+		Immutable
st_reverse(geometry: geometry) → geometry

Returns a modified geometry by reversing the order of its vertices.

+		Immutable
st_rotate(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_point: geometry) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_x: float, origin_y: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotatex(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the x axis by a rotation angle.

+		Immutable
st_rotatey(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the y axis by a rotation angle.

+		Immutable
st_rotatez(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the z axis by a rotation angle.

+		Immutable
st_s2covering(geography: geography) → geography

Returns a geography which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geography: geography, settings: string) → geography

Returns a geography which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geography, 's2_max_level=15,s2_level_mod=3').

+		Immutable
st_s2covering(geometry: geometry) → geometry

Returns a geometry which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geometry: geometry, settings: string) → geometry

Returns a geometry which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geometry, 's2_max_level=15,s2_level_mod=3')

+		Immutable
st_scale(g: geometry, factor: geometry) → geometry

Returns a modified Geometry scaled by taking in a Geometry as the factor.

+		Immutable
st_scale(g: geometry, factor: geometry, origin: geometry) → geometry

Returns a modified Geometry scaled by the Geometry factor relative to a false origin.

+		Immutable
st_scale(geometry: geometry, x_factor: float, y_factor: float) → geometry

Returns a modified Geometry scaled by the given factors.

+		Immutable
st_segmentize(geography: geography, max_segment_length_meters: float) → geography

Returns a modified Geography having no segment longer than the given max_segment_length meters.

+

The calculations are done on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_segmentize(geometry: geometry, max_segment_length: float) → geometry

Returns a modified Geometry having no segment longer than the given max_segment_length. Length units are in units of spatial reference.

+		Immutable
st_setpoint(line_string: geometry, index: int, point: geometry) → geometry

Sets the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_setsrid(geography: geography, srid: int) → geography

Sets a Geography to a new SRID without transforming the coordinates.

+		Immutable
st_setsrid(geometry: geometry, srid: int) → geometry

Sets a Geometry to a new SRID without transforming the coordinates.

+		Immutable
st_sharedpaths(geometry_a: geometry, geometry_b: geometry) → geometry

Returns a collection containing paths shared by the two input geometries.

+

Those going in the same direction are in the first element of the collection, +those going in the opposite direction are in the second element. +The paths themselves are given in the direction of the first geometry.

+		Immutable
st_shiftlongitude(geometry: geometry) → geometry

Returns a modified version of a geometry in which the longitude (X coordinate) of each point is incremented by 360 if it is <0 and decremented by 360 if it is >180. The result is only meaningful if the coordinates are in longitude/latitude.

+		Immutable
st_shortestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the minimum distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the minimum distance between the geometry’s vertexes. The function will return the shortest line that was discovered first when comparing minimum distances if more than one is found.

+		Immutable
st_simplify(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm.

+

This function utilizes the GEOS module.

+		Immutable
st_simplify(geometry: geometry, tolerance: float, preserve_collapsed: bool) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, retaining objects that would be too small given the tolerance if preserve_collapsed is set to true.

+		Immutable
st_simplifypreservetopology(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, avoiding the creation of invalid geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_snap(input: geometry, target: geometry, tolerance: float) → geometry

Snaps the vertices and segments of input geometry the target geometry’s vertices. +Tolerance is used to control where snapping is performed. The result geometry is the input geometry with the vertices snapped. +If no snapping occurs then the input geometry is returned unchanged.

+		Immutable
st_snaptogrid(geometry: geometry, origin: geometry, size_x: float, size_y: float, size_z: float, size_m: float) → geometry

Snap a geometry to a grid defined by the given origin and X, Y, Z, and M cell sizes. Any dimension with a 0 cell size will not be snapped.

+		Immutable
st_snaptogrid(geometry: geometry, origin_x: float, origin_y: float, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y based on an origin of (origin_x, origin_y).

+		Immutable
st_snaptogrid(geometry: geometry, size: float) → geometry

Snap a geometry to a grid of the given size. The specified size is only used to snap X and Y coordinates.

+		Immutable
st_snaptogrid(geometry: geometry, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y.

+		Immutable
st_srid(geography: geography) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geography as defined in spatial_ref_sys table.

+		Immutable
st_srid(geometry: geometry) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geometry as defined in spatial_ref_sys table.

+		Immutable
st_startpoint(geometry: geometry) → geometry

Returns the first point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_subdivide(geometry: geometry) → geometry

Returns a geometry divided into parts, where each part contains no more than 256 vertices.

+		Immutable
st_subdivide(geometry: geometry, max_vertices: int4) → geometry

Returns a geometry divided into parts, where each part contains no more than the number of vertices provided.

+		Immutable
st_summary(geography: geography) → string

Returns a text summary of the contents of the geography.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_summary(geometry: geometry) → string

Returns a text summary of the contents of the geometry.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_swapordinates(geometry: geometry, swap_ordinate_string: string) → geometry

Returns a version of the given geometry with given ordinates swapped. +The swap_ordinate_string parameter is a 2-character string naming the ordinates to swap. Valid names are: x, y, z and m.

+		Immutable
st_symdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_symmetricdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4, bounds: geometry) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4, bounds: geometry, margin: float) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, srid: int) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates. The supplied SRID is set on the new geometry.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, srid: int) → geometry

Transforms a geometry into the given SRID coordinate reference system by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system referenced by the projection text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float, delta_z: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_transscale(geometry: geometry, delta_x: float, delta_y: float, x_factor: float, y_factor: float) → geometry

Translates the geometry using the deltaX and deltaY args, then scales it using the XFactor, YFactor args, working in 2D only.

+		Immutable
st_unaryunion(geometry: geometry) → geometry

Returns a union of the components for any geometry or geometry collection provided. Dissolves boundaries of a multipolygon.

+		Immutable
st_voronoilines(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoipolygons(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_wkbtosql(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_wkttosql(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_x(geometry: geometry) → float

Returns the X coordinate of a geometry if it is a Point.

+		Immutable
st_xmax(box2d: box2d) → float

Returns the maximum X ordinate of a box2d.

+		Immutable
st_xmax(geometry: geometry) → float

Returns the maximum X ordinate of a geometry.

+		Immutable
st_xmin(box2d: box2d) → float

Returns the minimum X ordinate of a box2d.

+		Immutable
st_xmin(geometry: geometry) → float

Returns the minimum X ordinate of a geometry.

+		Immutable
st_y(geometry: geometry) → float

Returns the Y coordinate of a geometry if it is a Point.

+		Immutable
st_ymax(box2d: box2d) → float

Returns the maximum Y ordinate of a box2d.

+		Immutable
st_ymax(geometry: geometry) → float

Returns the maximum Y ordinate of a geometry.

+		Immutable
st_ymin(box2d: box2d) → float

Returns the minimum Y ordinate of a box2d.

+		Immutable
st_ymin(geometry: geometry) → float

Returns the minimum Y ordinate of a geometry.

+		Immutable
st_z(geometry: geometry) → float

Returns the Z coordinate of a geometry if it is a Point.

+		Immutable
st_zmflag(geometry: geometry) → int2

Returns a code based on the ZM coordinate dimension of a geometry (XY = 0, XYM = 1, XYZ = 2, XYZM = 3).

+		Immutable
+ +### String and byte functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ascii(val: string) → int

Returns the character code of the first character in val. Despite the name, the function supports Unicode too.

+		Immutable
bit_count(val: bytes) → int

Calculates the number of bits set used to represent val.

+		Immutable
bit_count(val: varbit) → int

Calculates the number of bits set used to represent val.

+		Immutable
bit_length(val: bytes) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: string) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
bitmask_and(a: string, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: string, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
btrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning or end of input (applies recursively).

+

For example, btrim('doggie', 'eod') returns ggi.

+		Immutable
btrim(val: string) → string

Removes all spaces from the beginning and end of val.

+		Immutable
char_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
char_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
character_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
character_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
chr(val: int) → string

Returns the character with the code given in val. Inverse function of ascii().

+		Immutable
compress(data: bytes, codec: string) → bytes

Compress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
concat(any...) → string

Concatenates a comma-separated list of strings.

+		Immutable
concat_ws(string, any...) → string

Uses the first argument as a separator between the concatenation of the subsequent arguments.

+

For example concat_ws('!','wow','great') returns wow!great.

+		Immutable
convert_from(str: bytes, enc: string) → string

Decode the bytes in str into a string using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
convert_to(str: string, enc: string) → bytes

Encode the string str as a byte array using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
decode(text: string, format: string) → bytes

Decodes data using format (hex / escape / base64).

+		Immutable
decompress(data: bytes, codec: string) → bytes

Decompress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
difference(source: string, target: string) → int

Convert two strings to their Soundex codes and report the number of matching code positions.

+		Immutable
encode(data: bytes, format: string) → string

Encodes data using format (hex / escape / base64).

+		Immutable
format(string, any...) → string

Interprets the first argument as a format string similar to C sprintf and interpolates the remaining arguments.

+		Stable
from_ip(val: bytes) → string

Converts the byte string representation of an IP to its character string representation.

+		Immutable
from_uuid(val: bytes) → string

Converts the byte string representation of a UUID to its character string representation.

+		Immutable
get_bit(bit_string: varbit, index: int) → int

Extracts a bit at given index in the bit array.

+		Immutable
get_bit(byte_string: bytes, index: int) → int

Extracts a bit at the given index in the byte array.

+		Immutable
get_byte(byte_string: bytes, index: int) → int

Extracts a byte at the given index in the byte array.

+		Immutable
initcap(val: string) → string

Capitalizes the first letter of val.

+		Immutable
left(input: bytes, return_set: int) → bytes

Returns the first return_set bytes from input.

+		Immutable
left(input: string, return_set: int) → string

Returns the first return_set characters from input.

+		Immutable
length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
length(val: string) → int

Calculates the number of characters in val.

+		Immutable
length(val: varbit) → int

Calculates the number of bits in val.

+		Immutable
lower(val: string) → string

Converts all characters in val to their lower-case equivalents.

+		Immutable
lpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the left of string.If string is longer than length it is truncated.

+		Immutable
lpad(string: string, length: int, fill: string) → string

Pads string by adding fill to the left of string to make it length. If string is longer than length it is truncated.

+		Immutable
ltrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning (left-hand side) of input (applies recursively).

+

For example, ltrim('doggie', 'od') returns ggie.

+		Immutable
ltrim(val: string) → string

Removes all spaces from the beginning (left-hand side) of val.

+		Immutable
md5(bytes...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
md5(string...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
octet_length(val: bytes) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: string) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int) → string

Replaces characters in input with overlay_val starting at start_pos (begins at 1).

+

For example, overlay('doggie', 'CAT', 2) returns dCATie.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int, end_pos: int) → string

Deletes the characters in input between start_pos and end_pos (count starts at 1), and then insert overlay_val at start_pos.

+		Immutable
parse_date(string: string, datestyle: string) → date

Parses a date assuming it is in format specified by DateStyle.

+		Immutable
parse_date(val: string) → date

Parses a date assuming it is in MDY format.

+		Immutable
parse_ident(qualified_identifier: string) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. Extra characters after the last identifier are considered an error

+		Immutable
parse_ident(qualified_identifier: string, strict: bool) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. If strict is false, then extra characters after the last identifier are ignored.

+		Immutable
parse_interval(string: string, style: string) → interval

Convert a string to an interval using the given IntervalStyle.

+		Immutable
parse_interval(val: string) → interval

Convert a string to an interval assuming the Postgres IntervalStyle.

+		Immutable
parse_time(string: string, timestyle: string) → time

Parses a time assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_time(val: string) → time

Parses a time assuming the date (if any) is in MDY format.

+		Immutable
parse_timestamp(string: string, datestyle: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates formatted using the given DateStyle.

+		Immutable
parse_timestamp(val: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates are in MDY format.

+		Immutable
parse_timetz(string: string, timestyle: string) → timetz

Parses a timetz assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_timetz(val: string) → timetz

Parses a timetz assuming the date (if any) is in MDY format.

+		Immutable
prettify_statement(statement: string, line_width: int, align_mode: int, case_mode: int) → string

Prettifies a statement using a user-configured pretty-printing config. +Align mode values range from 0 - 3, representing no, partial, full, and extra alignment respectively. +Case mode values range between 0 - 1, representing lower casing and upper casing respectively.

+		Immutable
prettify_statement(val: string) → string

Prettifies a statement using a the default pretty-printing config.

+		Immutable
quote_ident(val: string) → string

Return val suitably quoted to serve as identifier in a SQL statement.

+		Immutable
quote_literal(val: string) → string

Return val suitably quoted to serve as string literal in a SQL statement.

+		Immutable
quote_literal(val: anyelement) → string

Coerce val to a string and then quote it as a literal.

+		Stable
quote_nullable(val: string) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Immutable
quote_nullable(val: anyelement) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Stable
regexp_extract(input: string, regex: string) → string

Returns the first match for the Regular Expression regex in input.

+		Immutable
regexp_replace(input: string, regex: string, replace: string) → string

Replaces matches for the Regular Expression regex in input with the Regular Expression replace.

+		Immutable
regexp_replace(input: string, regex: string, replace: string, flags: string) → string

Replaces matches for the regular expression regex in input with the regular expression replace using flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
repeat(input: string, repeat_counter: int) → string

Concatenates input repeat_counter number of times.

+

For example, repeat('dog', 2) returns dogdog.

+		Immutable
replace(input: string, find: string, replace: string) → string

Replaces all occurrences of find with replace in input

+		Immutable
reverse(val: string) → string

Reverses the order of the string’s characters.

+		Immutable
right(input: bytes, return_set: int) → bytes

Returns the last return_set bytes from input.

+		Immutable
right(input: string, return_set: int) → string

Returns the last return_set characters from input.

+		Immutable
rpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the right of string. If string is longer than length it is truncated.

+		Immutable
rpad(string: string, length: int, fill: string) → string

Pads string to length by adding fill to the right of string. If string is longer than length it is truncated.

+		Immutable
rtrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the end (right-hand side) of input (applies recursively).

+

For example, rtrim('doggie', 'ei') returns dogg.

+		Immutable
rtrim(val: string) → string

Removes all spaces from the end (right-hand side) of val.

+		Immutable
set_bit(bit_string: varbit, index: int, to_set: int) → varbit

Updates a bit at given index in the bit array.

+		Immutable
set_bit(byte_string: bytes, index: int, to_set: int) → bytes

Updates a bit at the given index in the byte array.

+		Immutable
set_byte(byte_string: bytes, index: int, to_set: int) → bytes

Updates a byte at the given index in the byte array.

+		Immutable
sha1(bytes...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha1(string...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha224(bytes...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha224(string...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha256(bytes...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha256(string...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha384(bytes...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha384(string...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha512(bytes...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
sha512(string...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
similar_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_to_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
split_part(input: string, delimiter: string, return_index_pos: int) → string

Splits input using delimiter and returns the field at return_index_pos (starting from 1). If return_index_pos is negative, it returns the |return_index_pos|'th field from the end.

+

For example, split_part('123.456.789.0', '.', 3) returns 789.

+		Immutable
strpos(input: bytes, find: bytes) → int

Calculates the position where the byte subarray find begins in input.

+		Immutable
strpos(input: string, find: string) → int

Calculates the position where the string find begins in input.

+

For example, strpos('doggie', 'gie') returns 4.

+		Immutable
strpos(input: varbit, find: varbit) → int

Calculates the position where the bit subarray find begins in input.

+		Immutable
substr(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substr(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substr(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substring(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substring(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring_index(input: string, delim: string, count: int) → string

Returns a substring of input before count occurrences of delim. +If count is positive, the leftmost part is returned. If count is negative, the rightmost part is returned.

+		Immutable
to_char_with_style(date: date, datestyle: string) → string

Convert an date to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_char_with_style(interval: interval, style: string) → string

Convert an interval to a string using the given IntervalStyle.

+		Immutable
to_char_with_style(timestamp: timestamp, datestyle: string) → string

Convert an timestamp to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_english(val: int) → string

This function enunciates the value of its argument using English cardinals.

+		Immutable
to_hex(val: bytes) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: int) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: string) → string

Converts val to its hexadecimal representation.

+		Immutable
to_ip(val: string) → bytes

Converts the character string representation of an IP to its byte string representation.

+		Immutable
to_uuid(val: string) → bytes

Converts the character string representation of a UUID to its byte string representation.

+		Immutable
translate(input: string, find: string, replace: string) → string

In input, replaces the first character from find with the first character in replace; repeat for each character in find.

+

For example, translate('doggie', 'dog', '123'); returns 1233ie.

+		Immutable
ulid_to_uuid(val: string) → uuid

Converts a ULID string to its UUID-encoded representation.

+		Immutable
unaccent(val: string) → string

Removes accents (diacritic signs) from the text provided in val.

+		Immutable
upper(val: string) → string

Converts all characters in val to their to their upper-case equivalents.

+		Immutable
+ +### System info functions + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cluster_logical_timestamp() → decimal

Returns the logical time of the current transaction as +a CockroachDB HLC in decimal form.

+

Note that uses of this function disable server-side optimizations and +may increase either contention or retry errors, or both.

+

Returns an error if run in a transaction with an isolation level weaker than SERIALIZABLE.

+		Volatile
current_database() → string

Returns the current database.

+		Stable
current_schema() → string

Returns the current schema.

+		Stable
current_schemas(include_pg_catalog: bool) → string[]

Returns the valid schemas in the search path.

+		Stable
current_user() → string

Returns the current user. This function is provided for compatibility with PostgreSQL.

+		Stable
information_schema.crdb_datums_to_bytes(any...) → bytes

Converts datums into key-encoded bytes. Supports NULLs and all data types which may be used in index keys

+		Immutable
session_user() → string

Returns the session user. This function is provided for compatibility with PostgreSQL.

+		Stable
to_regclass(text: string) → regtype

Translates a textual relation name to its OID

+		Stable
to_regnamespace(text: string) → regtype

Translates a textual schema name to its OID

+		Stable
to_regproc(text: string) → regtype

Translates a textual function or procedure name to its OID

+		Stable
to_regprocedure(text: string) → regtype

Translates a textual function or procedure name(with argument types) to its OID

+		Stable
to_regrole(text: string) → regtype

Translates a textual role name to its OID

+		Stable
to_regtype(text: string) → regtype

Translates a textual type name to its OID

+		Stable
version() → string

Returns the node’s version of CockroachDB.

+		Volatile
+ +### System repair functions + + + + + +
Function → ReturnsDescriptionVolatility
information_schema.crdb_rewrite_inline_hints(statement_fingerprint: string, donor_sql: string) → int

This function adds an inline-hints rewrite rule for a statement fingerprint. It returns the hint ID of the newly created rewrite rule. The rewrite rule only applies to matching statement fingerprints. It first removes all inline hints from the target statement, and then copies inline hints from the donor statement.

+		Volatile
+ +### TIMETZ functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
current_time() → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time() → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_time(precision: int) → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time(precision: int) → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → timetz

Returns the current transaction’s time with time zone.

+		Stable
localtime(precision: int) → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime(precision: int) → timetz

Returns the current transaction’s time with time zone.

+		Stable
+ +### Trigrams functions + + + + + + +
Function → ReturnsDescriptionVolatility
show_trgm(input: string) → string[]

Returns an array of all the trigrams in the given string.

+		Immutable
similarity(left: string, right: string) → float

Returns a number that indicates how similar the two arguments are. The range of the result is zero (indicating that the two strings are completely dissimilar) to one (indicating that the two strings are identical).

+		Immutable
+ +### UUID functions + + + + + +
Function → ReturnsDescriptionVolatility
uuid_to_ulid(val: uuid) → string

Converts a UUID-encoded ULID to its string representation.

+		Immutable
+ +### Compatibility functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
col_description(table_oid: oid, column_number: int) → string

Returns the comment for a table column, which is specified by the OID of its table and its column number. (obj_description cannot be used for table columns, since columns do not have OIDs of their own.)

+		Stable
current_setting(setting_name: string) → string

System info

+		Stable
current_setting(setting_name: string, missing_ok: bool) → string

System info

+		Stable
format_type(type_oid: oid, typemod: int) → string

Returns the SQL name of a data type that is identified by its type OID and possibly a type modifier. Currently, the type modifier is ignored.

+		Stable
getdatabaseencoding() → string

Returns the current encoding name used by the database.

+		Stable
has_any_column_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_column_privilege(table: string, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: string, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_database_privilege(database: string, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(database: oid, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(user: string, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: string, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_foreign_data_wrapper_privilege(fdw: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(fdw: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_function_privilege(function: string, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(function: oid, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(user: string, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: string, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_language_privilege(language: string, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(language: oid, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(user: string, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: string, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_schema_privilege(schema: string, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(schema: oid, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_sequence_privilege(sequence: string, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(sequence: oid, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_server_privilege(server: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(server: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_system_privilege(privilege: string) → bool

Returns whether or not the current user has privileges for system.

+		Stable
has_system_privilege(user: string, privilege: string) → bool

Returns whether or not the user has privileges for system.

+		Stable
has_system_privilege(user: oid, privilege: string) → bool

Returns whether or not the user has privileges for system.

+		Stable
has_table_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_tablespace_privilege(tablespace: string, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(tablespace: oid, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_type_privilege(type: string, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(type: oid, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(user: string, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: string, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
information_schema._pg_numeric_precision(typid: oid, typmod: int4) → int

Returns the precision of the given type with type modifier

+		Immutable
information_schema._pg_numeric_precision_radix(typid: oid, typmod: int4) → int

Returns the radix of the given type with type modifier

+		Immutable
information_schema._pg_numeric_scale(typid: oid, typmod: int4) → int

Returns the scale of the given type with type modifier

+		Immutable
nameconcatoid(name: string, oid: oid) → name

Used in the information_schema to produce specific_name columns, which are supposed to be unique per schema. The result is the same as ($1::text || ‘_’ || $2::text)::name except that, if it would not fit in 63 characters, we make it do so by truncating the name input (not the oid).

+		Immutable
obj_description(object_oid: oid) → string

Returns the comment for a database object specified by its OID alone. This is deprecated since there is no guarantee that OIDs are unique across different system catalogs; therefore, the wrong comment might be returned.

+		Stable
obj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a database object specified by its OID and the name of the containing system catalog. For example, obj_description(123456, ‘pg_class’) would retrieve the comment for the table with OID 123456.

+		Stable
oidvectortypes(vector: oidvector) → string

Generates a comma seperated string of type names from an oidvector.

+		Stable
pg_backend_pid() → int

Returns a numerical ID attached to this session. This ID is part of the query cancellation key used by the wire protocol. This function was only added for compatibility, and unlike in Postgres, the returned value does not correspond to a real process ID.

+		Stable
pg_collation_for(str: anyelement) → string

Returns the collation of the argument

+		Stable
pg_column_is_updatable(reloid: oid, attnum: int2, include_triggers: bool) → bool

Returns whether the given column can be updated.

+		Stable
pg_column_size(any...) → int

Return size in bytes of the column provided as an argument

+		Stable
pg_function_is_visible(oid: oid) → bool

Returns whether the function with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_get_function_arg_default(func_oid: oid, arg_num: int4) → string

Get textual representation of a function argument’s default value. The second argument of this function is the argument number among all arguments (i.e. proallargtypes, not proargtypes), starting with 1, because that’s how information_schema.sql uses it.

+		Stable
pg_get_function_arguments(func_oid: oid) → string

Returns the argument list (with defaults) necessary to identify a function, in the form it would need to appear in within CREATE FUNCTION.

+		Stable
pg_get_function_identity_arguments(func_oid: oid) → string

Returns the argument list (without defaults) necessary to identify a function, in the form it would need to appear in within ALTER FUNCTION, for instance.

+		Stable
pg_get_function_result(func_oid: oid) → string

Returns the types of the result of the specified function.

+		Stable
pg_get_functiondef(func_oid: oid) → string

For user-defined functions, returns the definition of the specified function. For builtin functions, returns the name of the function.

+		Stable
pg_get_indexdef(index_oid: oid) → string

Gets the CREATE INDEX command for index

+		Stable
pg_get_indexdef(index_oid: oid, column_no: int, pretty_bool: bool) → string

Gets the CREATE INDEX command for index, or definition of just one index column when given a non-zero column number

+		Stable
pg_get_serial_sequence(table_name: string, column_name: string) → string

Returns the name of the sequence used by the given column_name in the table table_name.

+		Stable
pg_get_viewdef(view_oid: oid) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_get_viewdef(view_oid: oid, pretty_bool: bool) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_has_role(role: string, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(role: oid, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(user: string, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: string, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_is_other_temp_schema(oid: oid) → bool

Returns true if the given OID is the OID of another session’s temporary schema. (This can be useful, for example, to exclude other sessions’ temporary tables from a catalog display.)

+		Stable
pg_my_temp_schema() → oid

Returns the OID of the current session’s temporary schema, or zero if it has none (because it has not created any temporary tables).

+		Stable
pg_relation_is_updatable(reloid: oid, include_triggers: bool) → int4

Returns the update events the relation supports.

+		Stable
pg_sequence_last_value(sequence_oid: oid) → int

Returns the last value generated by a sequence, or NULL if the sequence has not been used yet.

+		Volatile
pg_sleep(seconds: float) → bool

pg_sleep makes the current session’s process sleep until seconds seconds have elapsed. seconds is a value of type double precision, so fractional-second delays can be specified.

+		Volatile
pg_table_is_visible(oid: oid) → bool

Returns whether the table with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_type_is_visible(oid: oid) → bool

Returns whether the type with the given OID belongs to one of the schemas on the search path.

+		Stable
set_config(setting_name: string, new_value: string, is_local: bool) → string

System info

+		Volatile
shobj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a shared database object specified by its OID and the name of the containing system catalog. This is just like obj_description except that it is used for retrieving comments on shared objects (e.g. databases).

+		Stable
+ diff --git a/src/current/_includes/cockroach-generated/release-26.1/sql/operators.md b/src/current/_includes/cockroach-generated/release-26.1/sql/operators.md new file mode 100644 index 00000000000..e79484b0754 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-26.1/sql/operators.md @@ -0,0 +1,684 @@ + + + + + +
#Return
int # intint
varbit # varbitvarbit
+ + + + +
#>Return
jsonb #> string[]jsonb
+ + + + +
#>>Return
jsonb #>> string[]string
+ + + + + + + + + +
%Return
decimal % decimaldecimal
decimal % intdecimal
float % floatfloat
int % decimaldecimal
int % intint
string % stringbool
+ + + + + + +
&Return
inet & inetinet
int & intint
varbit & varbitvarbit
+ + + + + + + + + +
&&Return
anyelement && anyelementbool
box2d && box2dbool
box2d && geometrybool
geometry && box2dbool
geometry && geometrybool
inet && inetbool
+ + + + + + + + + + + + + + + +
*Return
decimal * decimaldecimal
decimal * intdecimal
decimal * intervalinterval
float * floatfloat
float * intervalinterval
int * decimaldecimal
int * intint
int * intervalinterval
interval * decimalinterval
interval * floatinterval
interval * intinterval
vector * vectorvector
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Return
+decimaldecimal
+floatfloat
+intint
+intervalinterval
date + intdate
date + intervaltimestamp
date + timetimestamp
date + timetztimestamptz
decimal + decimaldecimal
decimal + intdecimal
decimal + pg_lsnpg_lsn
float + floatfloat
inet + intinet
int + datedate
int + decimaldecimal
int + inetinet
int + intint
interval + datetimestamp
interval + intervalinterval
interval + timetime
interval + timestamptimestamp
interval + timestamptztimestamptz
interval + timetztimetz
pg_lsn + decimalpg_lsn
time + datetimestamp
time + intervaltime
timestamp + intervaltimestamp
timestamptz + intervaltimestamptz
timetz + datetimestamptz
timetz + intervaltimetz
vector + vectorvector
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
-Return
-decimaldecimal
-floatfloat
-intint
-intervalinterval
date - dateint
date - intdate
date - intervaltimestamp
date - timetimestamp
decimal - decimaldecimal
decimal - intdecimal
float - floatfloat
inet - inetint
inet - intinet
int - decimaldecimal
int - intint
interval - intervalinterval
jsonb - intjsonb
jsonb - stringjsonb
jsonb - string[]jsonb
pg_lsn - decimalpg_lsn
pg_lsn - pg_lsndecimal
time - intervaltime
time - timeinterval
timestamp - intervaltimestamp
timestamp - timestampinterval
timestamp - timestamptzinterval
timestamptz - intervaltimestamptz
timestamptz - timestampinterval
timestamptz - timestamptzinterval
timetz - intervaltimetz
vector - vectorvector
+ + + + + +
->Return
jsonb -> intjsonb
jsonb -> stringjsonb
+ + + + + +
->>Return
jsonb ->> intstring
jsonb ->> stringstring
+ + + + + + + + + + +
/Return
decimal / decimaldecimal
decimal / intdecimal
float / floatfloat
int / decimaldecimal
int / intdecimal
interval / floatinterval
interval / intinterval
+ + + + + + + + +
//Return
decimal // decimaldecimal
decimal // intdecimal
float // floatfloat
int // decimaldecimal
int // intint
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<Return
anyenum < anyenumbool
bool < boolbool
bool[] < bool[]bool
box2d < box2dbool
bpchar < bpcharbool
bytes < bytesbool
bytes[] < bytes[]bool
collatedstring < collatedstringbool
collatedstring{*} < collatedstring{*}bool
date < datebool
date < timestampbool
date < timestamptzbool
date[] < date[]bool
decimal < decimalbool
decimal < floatbool
decimal < intbool
decimal[] < decimal[]bool
float < decimalbool
float < floatbool
float < intbool
float[] < float[]bool
geography < geographybool
geometry < geometrybool
inet < inetbool
inet[] < inet[]bool
int < decimalbool
int < floatbool
int < intbool
int < oidbool
int[] < int[]bool
interval < intervalbool
interval[] < interval[]bool
jsonb < jsonbbool
ltree < ltreebool
oid < intbool
oid < oidbool
pg_lsn < pg_lsnbool
refcursor < refcursorbool
string < stringbool
string[] < string[]bool
time < timebool
time < timetzbool
time[] < time[]bool
timestamp < datebool
timestamp < timestampbool
timestamp < timestamptzbool
timestamp[] < timestamp[]bool
timestamptz < datebool
timestamptz < timestampbool
timestamptz < timestamptzbool
timestamptz < timestamptzbool
timetz < timebool
timetz < timetzbool
tuple < tuplebool
uuid < uuidbool
uuid[] < uuid[]bool
varbit < varbitbool
vector < vectorbool
+ + + + +
<#>Return
vector <#> vectorfloat
+ + + + +
<->Return
vector <-> vectorfloat
+ + + + + + +
<<Return
inet << inetbool
int << intint
varbit << intvarbit
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<=Return
anyenum <= anyenumbool
bool <= boolbool
bool[] <= bool[]bool
box2d <= box2dbool
bpchar <= bpcharbool
bytes <= bytesbool
bytes[] <= bytes[]bool
collatedstring <= collatedstringbool
collatedstring{*} <= collatedstring{*}bool
date <= datebool
date <= timestampbool
date <= timestamptzbool
date[] <= date[]bool
decimal <= decimalbool
decimal <= floatbool
decimal <= intbool
decimal[] <= decimal[]bool
float <= decimalbool
float <= floatbool
float <= intbool
float[] <= float[]bool
geography <= geographybool
geometry <= geometrybool
inet <= inetbool
inet[] <= inet[]bool
int <= decimalbool
int <= floatbool
int <= intbool
int <= oidbool
int[] <= int[]bool
interval <= intervalbool
interval[] <= interval[]bool
jsonb <= jsonbbool
ltree <= ltreebool
oid <= intbool
oid <= oidbool
pg_lsn <= pg_lsnbool
refcursor <= refcursorbool
string <= stringbool
string[] <= string[]bool
time <= timebool
time <= timetzbool
time[] <= time[]bool
timestamp <= datebool
timestamp <= timestampbool
timestamp <= timestamptzbool
timestamp[] <= timestamp[]bool
timestamptz <= datebool
timestamptz <= timestampbool
timestamptz <= timestamptzbool
timestamptz <= timestamptzbool
timetz <= timebool
timetz <= timetzbool
tuple <= tuplebool
uuid <= uuidbool
uuid[] <= uuid[]bool
varbit <= varbitbool
vector <= vectorbool
+ + + + +
<=>Return
vector <=> vectorfloat
+ + + + + + +
<@Return
anyelement <@ anyelementbool
jsonb <@ jsonbbool
ltree <@ ltreebool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
=Return
anyenum = anyenumbool
bool = boolbool
bool[] = bool[]bool
box2d = box2dbool
bpchar = bpcharbool
bytes = bytesbool
bytes[] = bytes[]bool
collatedstring = collatedstringbool
collatedstring{*} = collatedstring{*}bool
date = datebool
date = timestampbool
date = timestamptzbool
date[] = date[]bool
decimal = decimalbool
decimal = floatbool
decimal = intbool
decimal[] = decimal[]bool
float = decimalbool
float = floatbool
float = intbool
float[] = float[]bool
geography = geographybool
geometry = geometrybool
inet = inetbool
inet[] = inet[]bool
int = decimalbool
int = floatbool
int = intbool
int = oidbool
int[] = int[]bool
interval = intervalbool
interval[] = interval[]bool
jsonb = jsonbbool
ltree = ltreebool
oid = intbool
oid = oidbool
pg_lsn = pg_lsnbool
refcursor = refcursorbool
string = stringbool
string[] = string[]bool
time = timebool
time = timetzbool
time[] = time[]bool
timestamp = datebool
timestamp = timestampbool
timestamp = timestamptzbool
timestamp[] = timestamp[]bool
timestamptz = datebool
timestamptz = timestampbool
timestamptz = timestamptzbool
timestamptz = timestamptzbool
timetz = timebool
timetz = timetzbool
tsquery = tsquerybool
tsvector = tsvectorbool
tuple = tuplebool
uuid = uuidbool
uuid[] = uuid[]bool
varbit = varbitbool
vector = vectorbool
+ + + + + + +
>>Return
inet >> inetbool
int >> intint
varbit >> intvarbit
+ + + + +
?Return
jsonb ? stringbool
+ + + + +
?&Return
jsonb ?& string[]bool
+ + + + +
?<@Return
ltree ?<@ ltreeltree
+ + + + +
?@>Return
ltree ?@> ltreeltree
+ + + + +
?|Return
jsonb ?| string[]bool
+ + + + + + +
@>Return
anyelement @> anyelementbool
jsonb @> jsonbbool
ltree @> ltreebool
+ + + + + +
@@Return
tsquery @@ tsvectorbool
tsvector @@ tsquerybool
+ + + + +
ILIKEReturn
string ILIKE stringbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
INReturn
anyenum IN tuplebool
bool IN tuplebool
box2d IN tuplebool
bpchar IN tuplebool
bytes IN tuplebool
collatedstring IN tuplebool
date IN tuplebool
decimal IN tuplebool
float IN tuplebool
geography IN tuplebool
geometry IN tuplebool
inet IN tuplebool
int IN tuplebool
interval IN tuplebool
jsonb IN tuplebool
ltree IN tuplebool
oid IN tuplebool
pg_lsn IN tuplebool
refcursor IN tuplebool
string IN tuplebool
time IN tuplebool
timestamp IN tuplebool
timestamptz IN tuplebool
timetz IN tuplebool
tuple IN tuplebool
uuid IN tuplebool
varbit IN tuplebool
vector IN tuplebool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IS NOT DISTINCT FROMReturn
anyelement IS NOT DISTINCT FROM unknownbool
anyenum IS NOT DISTINCT FROM anyenumbool
bool IS NOT DISTINCT FROM boolbool
bool[] IS NOT DISTINCT FROM bool[]bool
box2d IS NOT DISTINCT FROM box2dbool
bpchar IS NOT DISTINCT FROM bpcharbool
bytes IS NOT DISTINCT FROM bytesbool
bytes[] IS NOT DISTINCT FROM bytes[]bool
collatedstring IS NOT DISTINCT FROM collatedstringbool
collatedstring{*} IS NOT DISTINCT FROM collatedstring{*}bool
date IS NOT DISTINCT FROM datebool
date IS NOT DISTINCT FROM timestampbool
date IS NOT DISTINCT FROM timestamptzbool
date[] IS NOT DISTINCT FROM date[]bool
decimal IS NOT DISTINCT FROM decimalbool
decimal IS NOT DISTINCT FROM floatbool
decimal IS NOT DISTINCT FROM intbool
decimal[] IS NOT DISTINCT FROM decimal[]bool
float IS NOT DISTINCT FROM decimalbool
float IS NOT DISTINCT FROM floatbool
float IS NOT DISTINCT FROM intbool
float[] IS NOT DISTINCT FROM float[]bool
geography IS NOT DISTINCT FROM geographybool
geometry IS NOT DISTINCT FROM geometrybool
inet IS NOT DISTINCT FROM inetbool
inet[] IS NOT DISTINCT FROM inet[]bool
int IS NOT DISTINCT FROM decimalbool
int IS NOT DISTINCT FROM floatbool
int IS NOT DISTINCT FROM intbool
int IS NOT DISTINCT FROM oidbool
int[] IS NOT DISTINCT FROM int[]bool
interval IS NOT DISTINCT FROM intervalbool
interval[] IS NOT DISTINCT FROM interval[]bool
jsonb IS NOT DISTINCT FROM jsonbbool
jsonpath IS NOT DISTINCT FROM jsonpathbool
ltree IS NOT DISTINCT FROM ltreebool
oid IS NOT DISTINCT FROM intbool
oid IS NOT DISTINCT FROM oidbool
pg_lsn IS NOT DISTINCT FROM pg_lsnbool
refcursor IS NOT DISTINCT FROM refcursorbool
string IS NOT DISTINCT FROM stringbool
string[] IS NOT DISTINCT FROM string[]bool
time IS NOT DISTINCT FROM timebool
time IS NOT DISTINCT FROM timetzbool
time[] IS NOT DISTINCT FROM time[]bool
timestamp IS NOT DISTINCT FROM datebool
timestamp IS NOT DISTINCT FROM timestampbool
timestamp IS NOT DISTINCT FROM timestamptzbool
timestamp[] IS NOT DISTINCT FROM timestamp[]bool
timestamptz IS NOT DISTINCT FROM datebool
timestamptz IS NOT DISTINCT FROM timestampbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timetz IS NOT DISTINCT FROM timebool
timetz IS NOT DISTINCT FROM timetzbool
tsquery IS NOT DISTINCT FROM tsquerybool
tsvector IS NOT DISTINCT FROM tsvectorbool
tuple IS NOT DISTINCT FROM tuplebool
unknown IS NOT DISTINCT FROM unknownbool
unknown IS NOT DISTINCT FROM voidbool
uuid IS NOT DISTINCT FROM uuidbool
uuid[] IS NOT DISTINCT FROM uuid[]bool
varbit IS NOT DISTINCT FROM varbitbool
vector IS NOT DISTINCT FROM vectorbool
void IS NOT DISTINCT FROM unknownbool
+ + + + + +
LIKEReturn
collatedstring LIKE collatedstringbool
string LIKE stringbool
+ + + + +
SIMILAR TOReturn
string SIMILAR TO stringbool
+ + + + + + + + +
^Return
decimal ^ decimaldecimal
decimal ^ intdecimal
float ^ floatfloat
int ^ decimaldecimal
int ^ intint
+ + + + + + +
|Return
inet | inetinet
int | intint
varbit | varbitvarbit
+ + + + + +
|/Return
|/decimaldecimal
|/floatfloat
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
||Return
bool || bool[]bool[]
bool || stringstring
bool[] || boolbool[]
bool[] || bool[]bool[]
box2d || box2dbox2d
box2d || stringstring
bytes || bytesbytes
bytes || bytes[]bytes[]
bytes[] || bytesbytes[]
bytes[] || bytes[]bytes[]
date || date[]date[]
date || stringstring
date[] || datedate[]
date[] || date[]date[]
decimal || decimal[]decimal[]
decimal || stringstring
decimal[] || decimaldecimal[]
decimal[] || decimal[]decimal[]
float || float[]float[]
float || stringstring
float[] || floatfloat[]
float[] || float[]float[]
geography || geographygeography
geography || stringstring
geometry || geometrygeometry
geometry || stringstring
inet || inet[]inet[]
inet || stringstring
inet[] || inetinet[]
inet[] || inet[]inet[]
int || int[]int[]
int || stringstring
int[] || intint[]
int[] || int[]int[]
interval || interval[]interval[]
interval || stringstring
interval[] || intervalinterval[]
interval[] || interval[]interval[]
jsonb || jsonbjsonb
jsonb || stringstring
ltree || ltreeltree
ltree || stringstring
oid || oidoid
oid || stringstring
pg_lsn || pg_lsnpg_lsn
pg_lsn || stringstring
refcursor || refcursorrefcursor
refcursor || stringstring
string || boolstring
string || box2dstring
string || datestring
string || decimalstring
string || floatstring
string || geographystring
string || geometrystring
string || inetstring
string || intstring
string || intervalstring
string || jsonbstring
string || ltreestring
string || oidstring
string || pg_lsnstring
string || refcursorstring
string || stringstring
string || string[]string[]
string || timestring
string || timestampstring
string || timestamptzstring
string || timetzstring
string || tuplestring
string || uuidstring
string || varbitstring
string[] || stringstring[]
string[] || string[]string[]
time || stringstring
time || time[]time[]
time[] || timetime[]
time[] || time[]time[]
timestamp || stringstring
timestamp || timestamp[]timestamp[]
timestamp[] || timestamptimestamp[]
timestamp[] || timestamp[]timestamp[]
timestamptz || stringstring
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timetz || stringstring
timetz || timetztimetz
tuple || stringstring
uuid || stringstring
uuid || uuid[]uuid[]
uuid[] || uuiduuid[]
uuid[] || uuid[]uuid[]
varbit || stringstring
varbit || varbitvarbit
+ + + + + +
||/Return
||/decimaldecimal
||/floatfloat
+ + + + + + + + + + + +
~Return
~inetinet
~intint
~varbitvarbit
box2d ~ box2dbool
box2d ~ geometrybool
geometry ~ box2dbool
geometry ~ geometrybool
string ~ stringbool
+ + + + +
~*Return
string ~* stringbool
diff --git a/src/current/_includes/cockroach-generated/release-26.1/sql/window_functions.md b/src/current/_includes/cockroach-generated/release-26.1/sql/window_functions.md new file mode 100644 index 00000000000..321cc02ccf9 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-26.1/sql/window_functions.md @@ -0,0 +1,431 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cume_dist() → float

Calculates the relative rank of the current row: (number of rows preceding or peer with current row) / (total rows).

+		Immutable
dense_rank() → int

Calculates the rank of the current row without gaps; this function counts peer groups.

+		Immutable
first_value(val: bool) → bool

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: bytes) → bytes

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: date) → date

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: decimal) → decimal

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: float) → float

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: inet) → inet

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: int) → int

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: interval) → interval

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: string) → string

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: time) → time

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: uuid) → uuid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: box2d) → box2d

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geography) → geography

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geometry) → geometry

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: ltree) → ltree

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: oid) → oid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timetz) → timetz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: varbit) → varbit

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
lag(val: bool) → bool

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: bytes) → bytes

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: date) → date

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: date, n: int) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: decimal) → decimal

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: float) → float

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: float, n: int) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: inet) → inet

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: int) → int

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: int, n: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: interval) → interval

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: string) → string

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: string, n: int) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: time) → time

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: time, n: int) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamp) → timestamp

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz) → timestamptz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: uuid) → uuid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: box2d) → box2d

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geography) → geography

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geometry) → geometry

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: jsonb) → jsonb

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: ltree) → ltree

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: ltree, n: int) → ltree

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: ltree, n: int, default: ltree) → ltree

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: oid) → oid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn) → pg_lsn

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: refcursor) → refcursor

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timetz) → timetz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: varbit) → varbit

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
last_value(val: bool) → bool

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: bytes) → bytes

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: date) → date

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: decimal) → decimal

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: float) → float

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: inet) → inet

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: int) → int

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: interval) → interval

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: string) → string

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: time) → time

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: uuid) → uuid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: box2d) → box2d

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geography) → geography

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geometry) → geometry

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: ltree) → ltree

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: oid) → oid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timetz) → timetz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: varbit) → varbit

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
lead(val: bool) → bool

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: bytes) → bytes

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: date) → date

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: date, n: int) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: decimal) → decimal

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: float) → float

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: float, n: int) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: inet) → inet

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: int) → int

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: int, n: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: interval) → interval

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: string) → string

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: string, n: int) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: time) → time

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: time, n: int) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamp) → timestamp

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz) → timestamptz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: uuid) → uuid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: box2d) → box2d

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geography) → geography

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geometry) → geometry

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: jsonb) → jsonb

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: ltree) → ltree

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: ltree, n: int) → ltree

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: ltree, n: int, default: ltree) → ltree

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: oid) → oid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn) → pg_lsn

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: refcursor) → refcursor

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timetz) → timetz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: varbit) → varbit

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
nth_value(val: bool, n: int) → bool

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: bytes, n: int) → bytes

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: date, n: int) → date

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: decimal, n: int) → decimal

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: float, n: int) → float

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: inet, n: int) → inet

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: int, n: int) → int

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: interval, n: int) → interval

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: string, n: int) → string

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: time, n: int) → time

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: uuid, n: int) → uuid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: box2d, n: int) → box2d

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geography, n: int) → geography

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geometry, n: int) → geometry

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: ltree, n: int) → ltree

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: oid, n: int) → oid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timetz, n: int) → timetz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: varbit, n: int) → varbit

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
ntile(n: int) → int

Calculates an integer ranging from 1 to n, dividing the partition as equally as possible.

+		Immutable
percent_rank() → float

Calculates the relative rank of the current row: (rank - 1) / (total rows - 1).

+		Immutable
rank() → int

Calculates the rank of the current row with gaps; same as row_number of its first peer.

+		Immutable
row_number() → int

Calculates the number of the current row within its partition, counting from 1.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-26.2/eventlog.md b/src/current/_includes/cockroach-generated/release-26.2/eventlog.md new file mode 100644 index 00000000000..c891924297e --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-26.2/eventlog.md @@ -0,0 +1,4001 @@ +Certain notable events are reported using a structured format. +Commonly, these notable events are also copied to the table +`system.eventlog`, unless the cluster setting +`server.eventlog.enabled` is unset. + +Additionally, notable events are copied to specific external logging +channels in log messages, where they can be collected for further processing. + +The sections below document the possible notable event types +in this version of CockroachDB. For each event type, a table +documents the possible fields. A field may be omitted from +an event if its value is empty or zero. + +A field is also considered "Sensitive" if it may contain +application-specific information or personally identifiable information (PII). In that case, +the copy of the event sent to the external logging channel +will contain redaction markers in a format that is compatible +with the redaction facilities in [`cockroach debug zip`](cockroach-debug-zip.html) +and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html), +provided the `redactable` functionality is enabled on the logging sink. + +Events not documented on this page will have an unstructured format in log messages. + +## ASH events + +Events in this category pertain to Active Session History (ASH) +sampling diagnostics. + +Events in this category are logged to the `OPS` channel. + + +### `ash_workload_summary` + +An event of type `ash_workload_summary` is emitted periodically with a top-N summary of +the most frequently sampled workloads in the Active Session History +(ASH) buffer. One event is emitted per top-N entry. + +Reserved and subject to change without notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `WindowDurationMillis` | The duration of the reporting window in milliseconds. | no | +| `WorkEventType` | The work event type (e.g. CPU, IO, LOCK). | no | +| `WorkEvent` | The specific event name within the event type. | no | +| `WorkloadID` | The workload identifier (ex/ statement fingerprint). | no | +| `SampleCount` | The number of samples for this workload entry in the reporting window. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Changefeed telemetry events + +Events in this category pertain to changefeed usage and metrics. + +Events in this category are logged to the `CHANGEFEED` channel. + + +### `alter_changefeed` + +An event of type `alter_changefeed` is an event for any ALTER CHANGEFEED statements that are run. + +Note: in version 26.1, these events will be moved to the `CHANGEFEED` channel. +To test compatability before this, set the cluster setting +`log.channel_compatibility_mode.enabled` to false. This will send the +events to `CHANGEFEED` instead of `TELEMETRY`. + + +| Field | Description | Sensitive | +|--|--|--| +| `PreviousDescription` | The description of the changefeed job before the ALTER CHANGEFEED. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `changefeed_canceled` + +An event of type `changefeed_canceled` is an event for any changefeed cancellations. + +Note: in version 26.1, these events will be moved to the `CHANGEFEED` channel. +To test compatability before this, set the cluster setting +`log.channel_compatibility_mode.enabled` to false. This will send the +events to `CHANGEFEED` instead of `TELEMETRY`. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `changefeed_emitted_bytes` + +An event of type `changefeed_emitted_bytes` is an event representing the bytes emitted by a changefeed over an interval. + +Note: in version 26.1, these events will be moved to the `CHANGEFEED` channel. +To test compatability before this, set the cluster setting +`log.channel_compatibility_mode.enabled` to false. This will send the +events to `CHANGEFEED` instead of `TELEMETRY`. + + +| Field | Description | Sensitive | +|--|--|--| +| `EmittedBytes` | The number of bytes emitted. | no | +| `EmittedMessages` | The number of messages emitted. | no | +| `LoggingInterval` | The time period in nanoseconds between emitting telemetry events of this type (per-aggregator). | no | +| `Closing` | Flag to indicate that the changefeed is closing. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `changefeed_failed` + +An event of type `changefeed_failed` is an event for any changefeed failure since the plan hook +was triggered. + +Note: in version 26.1, these events will be moved to the `CHANGEFEED` channel. +To test compatability before this, set the cluster setting +`log.channel_compatibility_mode.enabled` to false. This will send the +events to `CHANGEFEED` instead of `TELEMETRY`. + + +| Field | Description | Sensitive | +|--|--|--| +| `FailureType` | The reason / environment with which the changefeed failed (ex: connection_closed, changefeed_behind). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +### `create_changefeed` + +An event of type `create_changefeed` is an event for any CREATE CHANGEFEED query that +successfully starts running. Failed CREATE statements will show up as +ChangefeedFailed events. + +Note: in version 26.1, these events moved to the `CHANGEFEED` channel. +To test compatability prior to this, set the cluster setting +`log.channel_compatibility_mode.enabled` to true. This will send the +events to `TELEMETRY` instead of `CHANGEFEED`. + + +| Field | Description | Sensitive | +|--|--|--| +| `Transformation` | Flag representing whether the changefeed is using CDC queries. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Description` | The description of that would show up in the job's description field, redacted | yes | +| `SinkType` | The type of sink being emitted to (ex: kafka, nodelocal, webhook-https). | no | +| `NumTables` | The number of tables listed in the query that the changefeed is to run on. | no | +| `Resolved` | The behavior of emitted resolved spans (ex: yes, no, 10s) | no | +| `InitialScan` | The desired behavior of initial scans (ex: yes, no, only) | no | +| `Format` | The data format being emitted (ex: JSON, Avro). | no | +| `JobId` | The job id for enterprise changefeeds. | no | + +## Cluster-level events + +Events in this category pertain to an entire cluster and are +not relative to any particular tenant. + +In a multi-tenant setup, the `system.eventlog` table for individual +tenants cannot contain a copy of cluster-level events; conversely, +the `system.eventlog` table in the system tenant cannot contain the +SQL-level events for individual tenants. + +Events in this category are logged to the `OPS` channel. + + +### `certs_reload` + +An event of type `certs_reload` is recorded when the TLS certificates are +reloaded/rotated from disk. + + +| Field | Description | Sensitive | +|--|--|--| +| `Success` | Whether the operation completed without errors. | no | +| `ErrorMessage` | If an error was encountered, the text of the error. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `disk_slowness_cleared` + +An event of type `disk_slowness_cleared` is recorded when disk slowness in a store has cleared. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `disk_slowness_detected` + +An event of type `disk_slowness_detected` is recorded when a store observes disk slowness +events. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `low_disk_space` + +An event of type `low_disk_space` is emitted when a store is reaching capacity, as we reach +certain thresholds. It is emitted periodically while we are in a low disk +state. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeID` | The node ID where the event was originated. | no | +| `StoreID` | | no | +| `PercentThreshold` | The free space percent threshold that we went under. | no | +| `AvailableBytes` | | no | +| `TotalBytes` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `node_decommissioned` + +An event of type `node_decommissioned` is recorded when a node is marked as +decommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_decommissioning` + +An event of type `node_decommissioning` is recorded when a node is marked as +decommissioning. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_join` + +An event of type `node_join` is recorded when a node joins the cluster. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_recommissioned` + +An event of type `node_recommissioned` is recorded when a decommissioning node is +recommissioned. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RequestingNodeID` | The node ID where the event was originated. | no | +| `TargetNodeID` | The node ID affected by the operation. | no | + +### `node_restart` + +An event of type `node_restart` is recorded when an existing node rejoins the cluster +after being offline. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_connection_timeout` + +An event of type `node_shutdown_connection_timeout` is recorded when SQL connections remain open +during shutdown, after waiting for the server.shutdown.connections.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still open after waiting for the client to close them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.connections.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `node_shutdown_transaction_timeout` + +An event of type `node_shutdown_transaction_timeout` is recorded when SQL transactions remain open +during shutdown, after waiting for the server.shutdown.transactions.timeout +to transpire. + + +| Field | Description | Sensitive | +|--|--|--| +| `Detail` | The detailed message, meant to be a human-understandable explanation. | no | +| `ConnectionsRemaining` | The number of connections still running SQL transactions after waiting for the client to end them. | no | +| `TimeoutMillis` | The amount of time the server waited for the client to close the connections, defined by server.shutdown.transactions.timeout. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `StartedAt` | The time when this node was last started. | no | +| `LastUp` | The approximate last time the node was up before the last restart. | no | + +### `tenant_shared_service_start` + +An event of type `tenant_shared_service_start` is recorded when a tenant server +is started inside the same process as the KV layer. + + +| Field | Description | Sensitive | +|--|--|--| +| `OK` | Whether the startup was successful. | no | +| `ErrorText` | If the startup failed, the text of the error. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +### `tenant_shared_service_stop` + +An event of type `tenant_shared_service_stop` is recorded when a tenant server +is shut down inside the same process as the KV layer. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event was originated. | no | +| `TenantID` | The ID of the tenant owning the service. | no | +| `InstanceID` | The ID of the server instance. | no | +| `TenantName` | The name of the tenant at the time the event was emitted. | yes | + +## Contention events + +Aggregated information about contention events. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `aggregated_contention_info` + +An event of type `aggregated_contention_info` is recorded periodically when contention events +are resolved. + + +| Field | Description | Sensitive | +|--|--|--| +| `WaitingStmtFingerprintId` | | no | +| `WaitingTxnFingerprintId` | | no | +| `BlockingTxnFingerprintId` | | no | +| `ContendedKey` | | partially | +| `Duration` | | no | +| `TableId` | Decoded key information (populated when key decoding is available). | no | +| `IndexId` | | no | +| `DatabaseName` | | no | +| `SchemaName` | | no | +| `TableName` | | no | +| `IndexName` | | no | +| `KeyColumnNames` | Decoded key column information. Arrays are parallel (same index = same column). Column names (schema metadata, safe). | no | +| `KeyColumnTypes` | Column types (schema metadata, safe). | no | +| `KeyColumnValues` | Column values (potentially sensitive user data). | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Debugging events + +Events in this category pertain to debugging operations performed by +operators or (more commonly) Cockroach Labs employees. These operations can +e.g. directly access and mutate internal state, breaking system invariants. + +Events in this category are logged to the `OPS` channel. + + +### `debug_recover_replica` + +An event of type `debug_recover_replica` is recorded when unsafe loss of quorum recovery is performed. + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `StoreID` | | no | +| `SurvivorReplicaID` | | no | +| `UpdatedReplicaID` | | no | +| `StartKey` | | yes | +| `EndKey` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +### `debug_send_kv_batch` + +An event of type `debug_send_kv_batch` is recorded when an arbitrary KV BatchRequest is submitted +to the cluster via the `debug send-kv-batch` CLI command. + + +| Field | Description | Sensitive | +|--|--|--| +| `BatchRequest` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `NodeID` | The node ID where the event originated. | no | +| `User` | The user which performed the operation. | yes | + +## Health events + +Events in this category pertain to the health of one or more servers. + +Events in this category are logged to the `HEALTH` channel. + + +### `hot_ranges_stats` + +An event of type `hot_ranges_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `RangeID` | | no | +| `Qps` | | no | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | yes | +| `LeaseholderNodeID` | LeaseholderNodeID indicates the Node ID that is the current leaseholder for the given range. | no | +| `WritesPerSecond` | Writes per second is the recent number of keys written per second on this range. | no | +| `ReadsPerSecond` | Reads per second is the recent number of keys read per second on this range. | no | +| `WriteBytesPerSecond` | Write bytes per second is the recent number of bytes written per second on this range. | no | +| `ReadBytesPerSecond` | Read bytes per second is the recent number of bytes read per second on this range. | no | +| `CPUTimePerSecond` | CPU time per second is the recent cpu usage in nanoseconds of this range. | no | +| `Databases` | Databases for the range. | no | +| `Tables` | Tables for the range | no | +| `Indexes` | Indexes for the range | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `runtime_stats` + +An event of type `runtime_stats` is recorded every 10 seconds as server health metrics. + + +| Field | Description | Sensitive | +|--|--|--| +| `MemRSSBytes` | The process resident set size. Expressed as bytes. | no | +| `GoroutineCount` | The number of goroutines. | no | +| `MemStackSysBytes` | The stack system memory used. Expressed as bytes. | no | +| `GoAllocBytes` | The memory allocated by Go. Expressed as bytes. | no | +| `GoTotalBytes` | The total memory allocated by Go but not released. Expressed as bytes. | no | +| `GoStatsStaleness` | The staleness of the Go memory statistics. Expressed in seconds. | no | +| `HeapFragmentBytes` | The amount of heap fragmentation. Expressed as bytes. | no | +| `HeapReservedBytes` | The amount of heap reserved. Expressed as bytes. | no | +| `HeapReleasedBytes` | The amount of heap released. Expressed as bytes. | no | +| `CGoAllocBytes` | The memory allocated outside of Go. Expressed as bytes. | no | +| `CGoTotalBytes` | The total memory allocated outside of Go but not released. Expressed as bytes. | no | +| `CGoCallRate` | The total number of calls outside of Go over time. Expressed as operations per second. | no | +| `CPUUserPercent` | The user CPU percentage. | no | +| `CPUSysPercent` | The system CPU percentage. | no | +| `GCPausePercent` | The GC pause percentage. | no | +| `GCRunCount` | The total number of GC runs. | no | +| `NetHostRecvBytes` | The bytes received on all network interfaces since this process started. | no | +| `NetHostSendBytes` | The bytes sent on all network interfaces since this process started. | no | +| `GoLimitBytes` | The soft Go memory limit in bytes. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Job events + +Events in this category pertain to long-running jobs that are orchestrated by +a node's job registry. These system processes can create and/or modify stored +objects during the course of their execution. + +A job might choose to emit multiple events during its execution when +transitioning from one "state" to another. +Egs: IMPORT/RESTORE will emit events on job creation and successful +completion. If the job fails, events will be emitted on job creation, +failure, and successful revert. + +Events in this category are logged to the `OPS` channel. + + +### `import` + +An event of type `import` is recorded when an import job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `restore` + +An event of type `restore` is recorded when a restore job is created and successful completion. +If the job fails, events will be emitted on job creation, failure, and +successful revert. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `JobID` | The ID of the job that triggered the event. | no | +| `JobType` | The type of the job that triggered the event. | no | +| `Description` | A description of the job that triggered the event. Some jobs populate the description with an approximate representation of the SQL statement run to create the job. | yes | +| `User` | The user account that triggered the event. | yes | +| `DescriptorIDs` | The object descriptors affected by the job. Set to zero for operations that don't affect descriptors. | yes | +| `Status` | The status of the job that triggered the event. This allows the job to indicate which phase execution it is in when the event is triggered. | no | + +### `status_change` + +An event of type `status_change` is recorded when a job changes statuses. + + +| Field | Description | Sensitive | +|--|--|--| +| `JobID` | The ID of the job that is changing statuses. | no | +| `JobType` | The type of the job that is changing statuses. | no | +| `Description` | A human parsable description of the status change | partially | +| `PreviousStatus` | The status that the job is transitioning out of | no | +| `NewStatus` | The status that the job has transitioned into | no | +| `RunNum` | The run number of the job. | no | +| `Error` | An error that may have occurred while the job was running. | yes | +| `FinalResumeErr` | An error that occurred that requires the job to be reverted. | yes | +| `User` | User is the owner of the job. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Miscellaneous SQL events + +Events in this category report miscellaneous SQL events. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own system.eventlog table. + +Events in this category are logged to the `OPS` channel. + + +### `delete_rewrite_inline_hints` + +An event of type `delete_rewrite_inline_hints` is recorded when a rewrite inline hint is +deleted via information_schema.crdb_delete_statement_hints. + + +| Field | Description | Sensitive | +|--|--|--| +| `StatementFingerprint` | The target statement fingerprint for which inline hints are being deleted. | no | +| `HintID` | The hint ID of the to-delete statement hint. | no | +| `DonorSql` | The donor sql of the deleted inline hint. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `delete_session_variable_hint` + +An event of type `delete_session_variable_hint` is recorded when a session variable hint is +deleted via information_schema.crdb_delete_statement_hints. + + +| Field | Description | Sensitive | +|--|--|--| +| `StatementFingerprint` | The target statement fingerprint for which the session variable hint is being deleted. | no | +| `HintID` | The hint ID of the deleted statement hint. | no | +| `VariableName` | The name of the session variable that was overridden. | no | +| `VariableValue` | The value of the session variable override. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `rewrite_inline_hints` + +An event of type `rewrite_inline_hints` is recorded when a new inline-hints rewrite rule is added +via information_schema.crdb_rewrite_inline_hints or crdb_internal.inject_hint. + + +| Field | Description | Sensitive | +|--|--|--| +| `StatementFingerprint` | The target statement fingerprint for which inline hints are being rewritten. | no | +| `DonorSQL` | The donor statement providing the inline hints. | no | +| `HintID` | The hint ID of the newly created statement hint. | no | +| `Database` | The database to which the hint is scoped, if any. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `set_cluster_setting` + +An event of type `set_cluster_setting` is recorded when a cluster setting is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | +| `DefaultValue` | The current default value of the cluster setting. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `set_session_variable_hint` + +An event of type `set_session_variable_hint` is recorded when a new session variable hint is +added via information_schema.crdb_set_session_variable_hint. + + +| Field | Description | Sensitive | +|--|--|--| +| `StatementFingerprint` | The target statement fingerprint for which the session variable is being overridden. | no | +| `VariableName` | The name of the session variable being overridden. | no | +| `VariableValue` | The value of the session variable override. | yes | +| `HintID` | The hint ID of the newly created statement hint. | no | +| `Database` | The database to which the hint is scoped, if any. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `set_tenant_cluster_setting` + +An event of type `set_tenant_cluster_setting` is recorded when a cluster setting override +is changed, either for another tenant or for all tenants. + + +| Field | Description | Sensitive | +|--|--|--| +| `SettingName` | The name of the affected cluster setting. | no | +| `Value` | The new value of the cluster setting. | yes | +| `TenantId` | The target Tenant ID. Empty if targeting all tenants. | no | +| `AllTenants` | Whether the override applies to all tenants. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +## SQL Access Audit Events + +Events in this category are generated when a table has been +marked as audited via `ALTER TABLE ... EXPERIMENTAL_AUDIT SET`. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SENSITIVE_ACCESS` channel. + + +### `admin_query` + +An event of type `admin_query` is recorded when a user with admin privileges (the user +is directly or indirectly a member of the admin role) executes a query. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `role_based_audit_event` + +An event of type `role_based_audit_event` is an audit event recorded when an executed query belongs to a user whose role +membership(s) correspond to any role that is enabled to emit an audit log via the sql.log.user_audit +cluster setting. + + +| Field | Description | Sensitive | +|--|--|--| +| `Role` | The configured audit role that emitted this log. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sensitive_table_access` + +An event of type `sensitive_table_access` is recorded when an access is performed to +a table marked as audited. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table being audited. | yes | +| `AccessMode` | How the table was accessed (r=read / rw=read/write). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `unsafe_internals_accessed` + +UnsafeInternalsAccess is recorded when a query accesses unsafe internals +using the allow_unsafe_internals override. + + +| Field | Description | Sensitive | +|--|--|--| +| `Query` | The query that triggered the unsafe internals access. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `unsafe_internals_denied` + +An event of type `unsafe_internals_denied` is recorded when a query attempts to access unsafe internals +but lacks the appropriate session variables. + + +| Field | Description | Sensitive | +|--|--|--| +| `Query` | The query that triggered the unsafe internals access. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +## SQL Execution Log + +Events in this category report executed queries. + +Note: These events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `query_execute` + +An event of type `query_execute` is recorded when a query is executed, +and the cluster setting `sql.log.all_statements.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +## SQL Logical Schema Changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the SQL logical +schema. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SQL_SCHEMA` channel. + + +### `alter_database_add_region` + +An event of type `alter_database_add_region` is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `RegionName` | The region being added. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_database_drop_region` + +AlterDatabaseAddRegion is recorded when a region is added to a database. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `RegionName` | The region being dropped. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_database_placement` + +An event of type `alter_database_placement` is recorded when the database placement is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `Placement` | The new placement policy. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_database_primary_region` + +An event of type `alter_database_primary_region` is recorded when a primary region is added/modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `PrimaryRegionName` | The new primary region. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_database_set_zone_config_extension` + +An event of type `alter_database_set_zone_config_extension` is recorded when a zone config extension is changed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `alter_database_survival_goal` + +An event of type `alter_database_survival_goal` is recorded when the survival goal is modified. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database. | no | +| `SurvivalGoal` | The new survival goal | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_function_options` + +An event of type `alter_function_options` is recorded when a user-defined function's options are +altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the affected function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_index` + +An event of type `alter_index` is recorded when an index is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_index_visible` + +AlterIndex is recorded when an index visibility is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `NotVisible` | Set true if index is not visible. NOTE: THIS FIELD IS DEPRECATED in favor of invisibility. | no | +| `Invisibility` | The new invisibility of the affected index. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_sequence` + +An event of type `alter_sequence` is recorded when a sequence is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_table` + +An event of type `alter_table` is recorded when a table is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update, if any. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_type` + +EventAlterType is recorded when a user-defined type is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_column` + +An event of type `comment_on_column` is recorded when a column is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected column. | no | +| `ColumnName` | The affected column. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_constraint` + +An event of type `comment_on_constraint` is recorded when an constraint is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected constraint. | no | +| `ConstraintName` | The name of the affected constraint. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_database` + +CommentOnTable is recorded when a database is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_index` + +An event of type `comment_on_index` is recorded when an index is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_schema` + + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | Name of the affected schema. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_table` + +An event of type `comment_on_table` is recorded when a table is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `comment_on_type` + +An event of type `comment_on_type` is recorded when a type is commented. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | +| `Comment` | The new comment. | yes | +| `NullComment` | Set to true if the comment was removed entirely. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_database` + +An event of type `create_database` is recorded when a database is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the new database. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_function` + +An event of type `create_function` is recorded when a user-defined function is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the created function. | no | +| `IsReplace` | If the new function is a replace of an existing function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_index` + +An event of type `create_index` is recorded when an index is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the new index. | no | +| `IndexName` | The name of the new index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_policy` + +An event of type `create_policy` is recorded when a policy is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the policy's table. | no | +| `PolicyName` | Name of the created policy. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_schema` + +An event of type `create_schema` is recorded when a schema is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the new schema. | no | +| `Owner` | The name of the owner for the new schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_sequence` + +An event of type `create_sequence` is recorded when a sequence is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the new sequence. | no | +| `Owner` | The name of the owner for the new sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_statistics` + +An event of type `create_statistics` is recorded when statistics are collected for a +table. + +Events of this type are only collected when the cluster setting +`sql.stats.post_events.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table for which the statistics were created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_table` + +An event of type `create_table` is recorded when a table is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the new table. | no | +| `Owner` | The name of the owner for the new table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_trigger` + +An event of type `create_trigger` is recorded when a trigger is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the trigger's table. | no | +| `TriggerName` | Name of the created trigger. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_type` + +An event of type `create_type` is recorded when a user-defined type is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the new type. | no | +| `Owner` | The name of the owner for the new type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_view` + +An event of type `create_view` is recorded when a view is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the new view. | no | +| `Owner` | The name of the owner of the new view. | no | +| `ViewQuery` | The SQL selection clause used to define the view. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_database` + +An event of type `drop_database` is recorded when a database is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | no | +| `DroppedSchemaObjects` | The names of the schemas dropped by a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_function` + +An event of type `drop_function` is recorded when a user-defined function is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | Name of the dropped function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_index` + +An event of type `drop_index` is recorded when an index is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the table containing the affected index. | no | +| `IndexName` | The name of the affected index. | no | +| `MutationID` | The mutation ID for the asynchronous job that is processing the index update. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_policy` + +An event of type `drop_policy` is recorded when a policy is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the policy's table. | no | +| `PolicyName` | Name of the dropped policy. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_schema` + +An event of type `drop_schema` is recorded when a schema is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_sequence` + +An event of type `drop_sequence` is recorded when a sequence is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `SequenceName` | The name of the affected sequence. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_table` + +An event of type `drop_table` is recorded when a table is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_trigger` + +An event of type `drop_trigger` is recorded when a trigger is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | Name of the trigger's table. | no | +| `TriggerName` | Name of the dropped trigger. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_type` + +An event of type `drop_type` is recorded when a user-defined type is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_view` + +An event of type `drop_view` is recorded when a view is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the affected view. | no | +| `CascadeDroppedViews` | The names of the views dropped as a result of a cascade operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `finish_schema_change` + +An event of type `finish_schema_change` is recorded when a previously initiated schema +change has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to complete. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `finish_schema_change_rollback` + +An event of type `finish_schema_change_rollback` is recorded when a previously +initiated schema change rollback has completed. + + +| Field | Description | Sensitive | +|--|--|--| +| `LatencyNanos` | The amount of time the schema change job took to rollback. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `force_delete_table_data_entry` + + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorID` | | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `refresh_materialized_view` + +An event of type `refresh_materialized_view` is recorded when a materialized view is refreshed. + + +| Field | Description | Sensitive | +|--|--|--| +| `ViewName` | The name of the materialized view being refreshed. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `rename_database` + +An event of type `rename_database` is recorded when a database is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The old name of the affected database. | no | +| `NewDatabaseName` | The new name of the affected database. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `rename_function` + +An event of type `rename_function` is recorded when a user-defined function is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The old name of the affected function. | no | +| `NewFunctionName` | The new name of the affected function. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `rename_schema` + +An event of type `rename_schema` is recorded when a schema is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The old name of the affected schema. | no | +| `NewSchemaName` | The new name of the affected schema. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `rename_table` + +An event of type `rename_table` is recorded when a table, sequence or view is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The old name of the affected table. | no | +| `NewTableName` | The new name of the affected table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `rename_type` + +An event of type `rename_type` is recorded when a user-defined type is renamed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The old name of the affected type. | no | +| `NewTypeName` | The new name of the affected type. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `reverse_schema_change` + +An event of type `reverse_schema_change` is recorded when an in-progress schema change +encounters a problem and is reversed. + + +| Field | Description | Sensitive | +|--|--|--| +| `Error` | The error encountered that caused the schema change to be reversed. The specific format of the error is variable and can change across releases without warning. | partially | +| `SQLSTATE` | The SQLSTATE code for the error. | no | +| `LatencyNanos` | The amount of time the schema change job took before being reverted. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `MutationID` | The descriptor mutation that this schema change was processing. | no | + +### `set_schema` + +An event of type `set_schema` is recorded when a table, view, sequence or type's schema is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DescriptorName` | The old name of the affected descriptor. | no | +| `NewDescriptorName` | The new name of the affected descriptor. | no | +| `DescriptorType` | The descriptor type being changed (table, view, sequence, type). | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `truncate_table` + +An event of type `truncate_table` is recorded when a table is truncated. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `unsafe_delete_descriptor` + +An event of type `unsafe_delete_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_delete_descriptor(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `unsafe_delete_namespace_entry` + +An event of type `unsafe_delete_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_delete_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `unsafe_upsert_descriptor` + +An event of type `unsafe_upsert_descriptor` is recorded when a descriptor is written +using crdb_internal.unsafe_upsert_descriptor(). + + +| Field | Description | Sensitive | +|--|--|--| +| `PreviousDescriptor` | | yes | +| `NewDescriptor` | | yes | +| `Force` | | no | +| `ForceNotice` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `unsafe_upsert_namespace_entry` + +An event of type `unsafe_upsert_namespace_entry` is recorded when a namespace entry is +written using crdb_internal.unsafe_upsert_namespace_entry(). + +The fields of this event type are reserved and can change across +patch releases without advance notice. + + +| Field | Description | Sensitive | +|--|--|--| +| `ParentID` | | no | +| `ParentSchemaID` | | no | +| `Name` | | no | +| `PreviousID` | | no | +| `Force` | | no | +| `FailedValidation` | | no | +| `ValidationErrors` | | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +## SQL Privilege changes + +Events in this category pertain to DDL (Data Definition Language) +operations performed by SQL statements that modify the privilege +grants for stored objects. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `PRIVILEGES` channel. + + +### `alter_database_owner` + +An event of type `alter_database_owner` is recorded when a database's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the database being affected. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_default_privileges` + +An event of type `alter_default_privileges` is recorded when default privileges are changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | +| `RoleName` | Either role_name should be populated or for_all_roles should be true. The role having its default privileges altered. | yes | +| `ForAllRoles` | Identifies if FOR ALL ROLES is used. | no | +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `alter_function_owner` + +AlterTableOwner is recorded when the owner of a user-defined function is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `FunctionName` | The name of the affected user-defined function. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_schema_owner` + +An event of type `alter_schema_owner` is recorded when a schema's owner is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_table_owner` + +An event of type `alter_table_owner` is recorded when the owner of a table, view or sequence is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected object. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `alter_type_owner` + +An event of type `alter_type_owner` is recorded when the owner of a user-defiend type is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | +| `Owner` | The name of the new owner. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `change_database_privilege` + +An event of type `change_database_privilege` is recorded when privileges are +added to / removed from a user for a database object. + + +| Field | Description | Sensitive | +|--|--|--| +| `DatabaseName` | The name of the affected database. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_function_privilege` + + + +| Field | Description | Sensitive | +|--|--|--| +| `FuncName` | The name of the affected function. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_schema_privilege` + +An event of type `change_schema_privilege` is recorded when privileges are added to / +removed from a user for a schema object. + + +| Field | Description | Sensitive | +|--|--|--| +| `SchemaName` | The name of the affected schema. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_table_privilege` + +An event of type `change_table_privilege` is recorded when privileges are added to / removed +from a user for a table, sequence or view object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The name of the affected table. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +### `change_type_privilege` + +An event of type `change_type_privilege` is recorded when privileges are added to / +removed from a user for a type object. + + +| Field | Description | Sensitive | +|--|--|--| +| `TypeName` | The name of the affected type. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Grantee` | The user/role affected by the grant or revoke operation. | yes | +| `GrantedPrivileges` | The privileges being granted to the grantee. | no | +| `RevokedPrivileges` | The privileges being revoked from the grantee. | no | + +## SQL Session events + +Events in this category report SQL client connections +and sessions. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these miscellaneous events are +preserved in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `SESSIONS` channel. + + +### `client_authentication_failed` + +An event of type `client_authentication_failed` is reported when a client session +did not authenticate successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Reason` | The reason for the authentication failure. See below for possible values for type `AuthFailReason`. | no | +| `Detail` | The detailed error for the authentication failure. | partially | +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | partially | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | partially | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | partially | + +### `client_authentication_info` + +An event of type `client_authentication_info` is reported for intermediate +steps during the authentication process. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used, once known. | no | +| `Info` | The authentication progress message. | partially | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | partially | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | partially | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | partially | + +### `client_authentication_ok` + +An event of type `client_authentication_ok` is reported when a client session +was authenticated successfully. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Method` | The authentication method used. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | partially | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | partially | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | partially | + +### `client_connection_end` + +An event of type `client_connection_end` is reported when a client connection +is closed. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | partially | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_connection_start` + +An event of type `client_connection_start` is reported when a client connection +is established. This is reported even when authentication +fails, and even for simple cancellation messages. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_connections.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | partially | +| `SessionID` | The connection's hex encoded session id. | no | + +### `client_session_end` + +An event of type `client_session_end` is reported when a client session +is completed. + +Events of this type are only emitted when the cluster setting +`server.auth_log.sql_sessions.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `Duration` | The duration of the connection in nanoseconds. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `InstanceID` | The instance ID (not tenant ID) of the SQL server where the event was originated. | no | +| `Network` | The network protocol for this connection: tcp4, tcp6, unix, etc. | no | +| `RemoteAddress` | The remote address of the SQL client. Note that when using a proxy or other intermediate server, this field will contain the address of the intermediate server. | partially | +| `SessionID` | The connection's hex encoded session id. | no | +| `Transport` | The connection type after transport negotiation. | no | +| `User` | The database username the session is for. This username will have undergone case-folding and Unicode normalization. | partially | +| `SystemIdentity` | The original system identity provided by the client, if an identity mapping was used per Host-Based Authentication rules. This may be a GSSAPI or X.509 principal or any other external value, so no specific assumptions should be made about the contents of this field. | partially | + +## SQL Slow Query Log + +Events in this category report slow query execution. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +In version 26.1, these events moved to the `SQL_EXEC` channel. +To test compatability prior to this, set the cluster setting +`log.channel_compatibility_mode.enabled` to true. This will send the +events to `SQL_PERF` instead of `SQL_EXEC`. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `large_row` + +An event of type `large_row` is recorded when a statement tries to write a row larger than +cluster setting `sql.guardrails.max_row_size_log` to the database. Multiple +LargeRow events will be recorded for statements writing multiple large rows. +LargeRow events are recorded before the transaction commits, so in the case +of transaction abort there will not be a corresponding row in the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `scan_row_count_misestimate` + +An event of type `scan_row_count_misestimate` is recorded when the optimizer's row count estimate +for a logical scan differs significantly from the actual number of rows read, +and cluster setting `sql.log.scan_row_count_misestimate.enabled` is set. + + +| Field | Description | Sensitive | +|--|--|--| +| `TableName` | The fully qualified name of the table being scanned. | no | +| `IndexName` | The name of the index being scanned. | no | +| `EstimatedRowCount` | The optimizer's estimated row count for the scan. | no | +| `ActualRowCount` | The actual number of rows read by all processors performing the scan. | no | +| `NanosSinceStatsCollected` | Time in nanoseconds that have passed since full stats were collected on the table. | no | +| `EstimatedStaleness` | Estimated fraction of stale rows in the table based on the time since stats were last collected. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `slow_query` + +An event of type `slow_query` is recorded when a query triggers the "slow query" condition. + +As of this writing, the condition requires: +- the cluster setting `sql.log.slow_query.latency_threshold` +set to a non-zero value, AND +- EITHER of the following conditions: +- the actual age of the query exceeds the configured threshold; AND/OR +- the query performs a full table/index scan AND the cluster setting +`sql.log.slow_query.experimental_full_table_scans.enabled` is set. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit` + +An event of type `txn_rows_read_limit` is recorded when a transaction tries to read more rows than +cluster setting `sql.defaults.transaction_rows_read_log`. There will only be +a single record for a single transaction (unless it is retried) even if there +are more statement within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit` + +An event of type `txn_rows_written_limit` is recorded when a transaction tries to write more rows +than cluster setting `sql.defaults.transaction_rows_written_log`. There will +only be a single record for a single transaction (unless it is retried) even +if there are more mutation statements within the transaction that haven't +been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL Slow Query Log (Internal) + +Events in this category report slow query execution by +internal executors, i.e., when CockroachDB internally issues +SQL statements. + +Note: these events are not written to `system.eventlog`, even +when the cluster setting `system.eventlog.enabled` is set. They +are only emitted via external logging. + +In version 26.1, these events moved to the `SQL_EXEC` channel. +To test compatability prior to this, set the cluster setting +`log.channel_compatibility_mode.enabled` to true. This will send the +events to `SQL_INTERNAL_PERF` instead of `SQL_EXEC`. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `large_row_internal` + +An event of type `large_row_internal` is recorded when an internal query tries to write a row +larger than cluster settings `sql.guardrails.max_row_size_log` or +`sql.guardrails.max_row_size_err` to the database. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `RowSize` | | no | +| `TableID` | | no | +| `FamilyID` | | no | +| `PrimaryKey` | | yes | + +### `slow_query_internal` + +An event of type `slow_query_internal` is recorded when a query triggers the "slow query" condition, +and the cluster setting `sql.log.slow_query.internal_queries.enabled` is +set. +See the documentation for the event type `slow_query` for details about +the "slow query" condition. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `txn_rows_read_limit_internal` + +An event of type `txn_rows_read_limit_internal` is recorded when an internal transaction tries to +read more rows than cluster setting `sql.defaults.transaction_rows_read_log` +or `sql.defaults.transaction_rows_read_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +### `txn_rows_written_limit_internal` + +An event of type `txn_rows_written_limit_internal` is recorded when an internal transaction tries to +write more rows than cluster setting +`sql.defaults.transaction_rows_written_log` or +`sql.defaults.transaction_rows_written_err`. There will only be a single +record for a single transaction (unless it is retried) even if there are more +mutation statements within the transaction that haven't been executed yet. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `TxnID` | TxnID is the ID of the transaction that hit the row count limit. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `NumRows` | NumRows is the number of rows written/read (depending on the event type) by the transaction that reached the corresponding guardrail. | no | + +## SQL User and Role operations + +Events in this category pertain to SQL statements that modify the +properties of users and roles. + +They are relative to a particular SQL tenant. +In a multi-tenant setup, copies of DDL-related events are preserved +in each tenant's own `system.eventlog` table. + +Events in this category are logged to the `USER_ADMIN` channel. + + +### `alter_role` + +An event of type `alter_role` is recorded when a role is altered. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | +| `Options` | The options set on the user/role. | no | +| `SetInfo` | Information corresponding to an ALTER ROLE SET statement. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `create_role` + +An event of type `create_role` is recorded when a role is created. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the new user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `drop_role` + +An event of type `drop_role` is recorded when a role is dropped. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the affected user/role. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `grant_role` + +An event of type `grant_role` is recorded when a role is granted. + + +| Field | Description | Sensitive | +|--|--|--| +| `GranteeRoles` | The roles being granted to. | yes | +| `Members` | The roles being granted. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | + +### `password_hash_converted` + +An event of type `password_hash_converted` is recorded when the password credentials +are automatically converted server-side. + + +| Field | Description | Sensitive | +|--|--|--| +| `RoleName` | The name of the user/role whose credentials have been converted. | yes | +| `OldMethod` | The previous hash method. | no | +| `NewMethod` | The new hash method. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Sampled SQL Events + +Events in this category report sample of SQL events. + +Events in this category are logged to the `SQL_EXEC` channel. + + +### `m_v_c_c_iterator_stats` + +Internal storage iteration statistics for a single execution. + + +| Field | Description | Sensitive | +|--|--|--| +| `StepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `StepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `SeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `BlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `BlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `KeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `ValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `PointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `RangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | + + + +### `sampled_exec_stats` + +An event of type `sampled_exec_stats` contains execution statistics that apply to both statements +and transactions. These stats as a whole are collected using a sampling approach. +These exec stats are meant to contain the same fields as ExecStats in +apps_stats.proto but are for a single execution rather than aggregated executions. +Fields in this struct should be updated in sync with apps_stats.proto. + + +| Field | Description | Sensitive | +|--|--|--| +| `NetworkBytes` | NetworkBytes collects the number of bytes sent over the network by DistSQL components. | no | +| `MaxMemUsage` | MaxMemUsage collects the maximum memory usage that occurred on a node. | no | +| `ContentionTime` | ContentionTime collects the time in seconds statements in the transaction spent contending. | no | +| `NetworkMessages` | NetworkMessages collects the number of messages that were sent over the network by DistSQL components. | no | +| `MaxDiskUsage` | MaxDiskUsage collects the maximum temporary disk usage that occurred. This is set in cases where a query had to spill to disk, e.g. when performing a large sort where not all of the tuples fit in memory. | no | +| `CPUSQLNanos` | CPUSQLNanos collects the CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `MVCCIteratorStats` | Internal storage iteration statistics. | yes | +| `AdmissionWaitTime` | AdmissionWaitTime is the cumulative time spent in admission control queues. | no | + + + +### `sampled_query` + +An event of type `sampled_query` is the SQL query event logged to the telemetry channel. It +contains common SQL event/execution details. + +Note: in version 26.1, these events moved to the `SQL_EXEC` channel. +To test compatability prior to this, set the cluster setting +`log.channel_compatibility_mode.enabled` to true. This will send the +events to `TELEMETRY` instead of `SQL_EXEC`. + + +| Field | Description | Sensitive | +|--|--|--| +| `SkippedQueries` | skipped_queries indicate how many SQL statements were not considered for sampling prior to this one. If the field is omitted, or its value is zero, this indicates that no statement was omitted since the last event. | no | +| `CostEstimate` | Cost of the query as estimated by the optimizer. | no | +| `Distribution` | The distribution of the DistSQL query plan (local, full, or partial). | no | +| `PlanGist` | The query's plan gist bytes as a base64 encoded string. | no | +| `SessionID` | SessionID is the ID of the session that initiated the query. | no | +| `Database` | Name of the database that initiated the query. | no | +| `StatementID` | Statement ID of the query. | no | +| `TransactionID` | Transaction ID of the query. | no | +| `MaxFullScanRowsEstimate` | Maximum number of rows scanned by a full scan, as estimated by the optimizer. | no | +| `TotalScanRowsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer. | no | +| `OutputRowsEstimate` | The number of rows output by the query, as estimated by the optimizer. | no | +| `StatsAvailable` | Whether table statistics were available to the optimizer when planning the query. | no | +| `NanosSinceStatsCollected` | The maximum number of nanoseconds that have passed since stats were collected on any table scanned by this query. | no | +| `BytesRead` | The number of bytes read from disk. | no | +| `RowsRead` | The number of rows read from disk. | no | +| `RowsWritten` | The number of rows written. | no | +| `InnerJoinCount` | The number of inner joins in the query plan. | no | +| `LeftOuterJoinCount` | The number of left (or right) outer joins in the query plan. | no | +| `FullOuterJoinCount` | The number of full outer joins in the query plan. | no | +| `SemiJoinCount` | The number of semi joins in the query plan. | no | +| `AntiJoinCount` | The number of anti joins in the query plan. | no | +| `IntersectAllJoinCount` | The number of intersect all joins in the query plan. | no | +| `ExceptAllJoinCount` | The number of except all joins in the query plan. | no | +| `HashJoinCount` | The number of hash joins in the query plan. | no | +| `CrossJoinCount` | The number of cross joins in the query plan. | no | +| `IndexJoinCount` | The number of index joins in the query plan. | no | +| `LookupJoinCount` | The number of lookup joins in the query plan. | no | +| `MergeJoinCount` | The number of merge joins in the query plan. | no | +| `InvertedJoinCount` | The number of inverted joins in the query plan. | no | +| `ApplyJoinCount` | The number of apply joins in the query plan. | no | +| `ZigZagJoinCount` | The number of zig zag joins in the query plan. | no | +| `ContentionNanos` | The duration of time in nanoseconds that the query experienced contention. | no | +| `Regions` | The regions of the nodes where SQL processors ran. | no | +| `NetworkBytesSent` | The number of network bytes by DistSQL components. | no | +| `MaxMemUsage` | The maximum amount of memory usage by nodes for this query. | no | +| `MaxDiskUsage` | The maximum amount of disk usage by nodes for this query. | no | +| `KVBytesRead` | The number of bytes read at the KV layer for this query. | no | +| `KVPairsRead` | The number of key-value pairs read at the KV layer for this query. | no | +| `KVRowsRead` | The number of rows read at the KV layer for this query. | no | +| `NetworkMessages` | The number of network messages sent by nodes for this query by DistSQL components. | no | +| `IndexRecommendations` | Generated index recommendations for this query. | no | +| `ScanCount` | The number of scans in the query plan. | no | +| `ScanWithStatsCount` | The number of scans using statistics (including forecasted statistics) in the query plan. | no | +| `ScanWithStatsForecastCount` | The number of scans using forecasted statistics in the query plan. | no | +| `TotalScanRowsWithoutForecastsEstimate` | Total number of rows read by all scans in the query, as estimated by the optimizer without using forecasts. | no | +| `NanosSinceStatsForecasted` | The greatest quantity of nanoseconds that have passed since the forecast time (or until the forecast time, if it is in the future, in which case it will be negative) for any table with forecasted stats scanned by this query. | no | +| `Indexes` | The list of indexes used by this query. | no | +| `CpuTimeNanos` | Collects the cumulative CPU time spent executing SQL operations in nanoseconds. Currently, it is only collected for statements without mutations that have a vectorized plan. | no | +| `KvGrpcCalls` | The number of grpc calls done to get data form KV nodes | no | +| `KvTimeNanos` | Cumulated time spent waiting for a KV request. This includes disk IO time and potentially network time (if any of the keys are not local). | no | +| `ServiceLatencyNanos` | The time to service the query, from start of parse to end of execute. | no | +| `OverheadLatencyNanos` | The difference between service latency and the sum of parse latency + plan latency + run latency . | no | +| `RunLatencyNanos` | The time to run the query and fetch or compute the result rows. | no | +| `PlanLatencyNanos` | The time to transform the AST into a logical query plan. | no | +| `IdleLatencyNanos` | The time between statement executions in a transaction | no | +| `ParseLatencyNanos` | The time to transform the SQL string into an abstract syntax tree (AST). | no | +| `MvccStepCount` | StepCount collects the number of times the iterator moved forward or backward over the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccStepCountInternal` | StepCountInternal collects the number of times the iterator moved forward or backward over LSM internal keys. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCount` | SeekCount collects the number of times the iterator moved to a specific key/value pair in the DB's underlying storage keyspace. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccSeekCountInternal` | SeekCountInternal collects the number of times the iterator moved to a specific LSM internal key. For details, see pkg/storage/engine.go and pkg/sql/opt/exec/factory.go. | no | +| `MvccBlockBytes` | BlockBytes collects the bytes in the loaded SSTable data blocks. For details, see pebble.InternalIteratorStats. | no | +| `MvccBlockBytesInCache` | BlockBytesInCache collects the subset of BlockBytes in the block cache. For details, see pebble.InternalIteratorStats. | no | +| `MvccKeyBytes` | KeyBytes collects the bytes in keys that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccValueBytes` | ValueBytes collects the bytes in values that were iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointCount` | PointCount collects the count of point keys iterated over. For details, see pebble.InternalIteratorStats. | no | +| `MvccPointsCoveredByRangeTombstones` | PointsCoveredByRangeTombstones collects the count of point keys that were iterated over that were covered by range tombstones. For details, see pebble.InternalIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyCount` | RangeKeyCount collects the count of range keys encountered during iteration. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeyContainedPoints` | RangeKeyContainedPoints collects the count of point keys encountered within the bounds of a range key. For details, see pebble.RangeKeyIteratorStats and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `MvccRangeKeySkippedPoints` | RangeKeySkippedPoints collects the count of the subset of ContainedPoints point keys that were skipped during iteration due to range-key masking. For details, see pkg/storage/engine.go, pebble.RangeKeyIteratorStats, and docs/tech-notes/mvcc-range-tombstones.md. | no | +| `SchemaChangerMode` | SchemaChangerMode is the mode that was used to execute the schema change, if any. | no | +| `SQLInstanceIDs` | SQLInstanceIDs is a list of all the SQL instances used in this statement's execution. | no | +| `KVNodeIDs` | KVNodeIDs is a list of all the KV nodes used in this statement's execution. | no | +| `StatementFingerprintID` | Statement fingerprint ID of the query. | no | +| `UsedFollowerRead` | UsedFollowerRead indicates whether at least some reads were served by the follower replicas. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `ExecMode` | How the statement was being executed (exec/prepare, etc.) | no | +| `NumRows` | Number of rows returned. For mutation statements (INSERT, etc) that do not produce result rows, this field reports the number of rows affected. | no | +| `SQLSTATE` | The SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | The text of the error if any. | partially | +| `Age` | Age of the query in milliseconds. | no | +| `NumRetries` | Number of retries, when the txn was reretried automatically by the server. | no | +| `FullTableScan` | Whether the query contains a full table scan. | no | +| `FullIndexScan` | Whether the query contains a full secondary index scan of a non-partial index. | no | +| `TxnCounter` | The sequence number of the SQL transaction inside its session. | no | +| `BulkJobId` | The job id for bulk job (IMPORT/BACKUP/RESTORE). | no | +| `StmtPosInTxn` | The statement's index in the transaction, starting at 1. | no | + +### `sampled_transaction` + +An event of type `sampled_transaction` is the event logged to telemetry at the end of transaction execution. + +Note: in version 26.1, these events moved to the `SQL_EXEC` channel. +To test compatability prior to this, set the cluster setting +`log.channel_compatibility_mode.enabled` to true. This will send the +events to `TELEMETRY` instead of `SQL_EXEC`. + + +| Field | Description | Sensitive | +|--|--|--| +| `User` | User is the user account that triggered the transaction. The special usernames `root` and `node` are not considered sensitive. | depends | +| `ApplicationName` | ApplicationName is the application name for the session where the transaction was executed. This is included in the event to ease filtering of logging output by application. | no | +| `TxnCounter` | TxnCounter is the sequence number of the SQL transaction inside its session. | no | +| `SessionID` | SessionID is the ID of the session that initiated the transaction. | no | +| `TransactionID` | TransactionID is the id of the transaction. | no | +| `Committed` | Committed indicates if the transaction committed successfully. We want to include this value even if it is false. | no | +| `ImplicitTxn` | ImplicitTxn indicates if the transaction was an implicit one. We want to include this value even if it is false. | no | +| `StartTimeUnixNanos` | StartTimeUnixNanos is the time the transaction was started. Expressed as unix time in nanoseconds. | no | +| `EndTimeUnixNanos` | EndTimeUnixNanos the time the transaction finished (either committed or aborted). Expressed as unix time in nanoseconds. | no | +| `ServiceLatNanos` | ServiceLatNanos is the time to service the whole transaction, from start to end of execution. | no | +| `SQLSTATE` | SQLSTATE is the SQLSTATE code for the error, if an error was encountered. Empty/omitted if no error. | no | +| `ErrorText` | ErrorText is the text of the error if any. | partially | +| `NumRetries` | NumRetries is the number of time when the txn was retried automatically by the server. | no | +| `LastAutoRetryReason` | LastAutoRetryReason is a string containing the reason for the last automatic retry. | partially | +| `NumRows` | NumRows is the total number of rows returned across all statements. | no | +| `RetryLatNanos` | RetryLatNanos is the amount of time spent retrying the transaction. | no | +| `CommitLatNanos` | CommitLatNanos is the amount of time spent committing the transaction after all statement operations. | no | +| `IdleLatNanos` | IdleLatNanos is the amount of time spent waiting for the client to send statements while the transaction is open. | no | +| `BytesRead` | BytesRead is the number of bytes read from disk. | no | +| `RowsRead` | RowsRead is the number of rows read from disk. | no | +| `RowsWritten` | RowsWritten is the number of rows written to disk. | no | +| `SampledExecStats` | SampledExecStats is a nested field containing execution statistics. This field will be omitted if the stats were not sampled. | yes | +| `SkippedTransactions` | SkippedTransactions is the number of transactions that were skipped as part of sampling prior to this one. We only count skipped transactions when telemetry logging is enabled and the sampling mode is set to "transaction". | no | +| `TransactionFingerprintID` | TransactionFingerprintID is the fingerprint ID of the transaction. This can be used to find the transaction in the console. | no | +| `StatementFingerprintIDs` | StatementFingerprintIDs is an array of statement fingerprint IDs belonging to this transaction. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Storage telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `level_stats` + +An event of type `level_stats` contains per-level statistics for an LSM. + + +| Field | Description | Sensitive | +|--|--|--| +| `Level` | level is the level ID in a LSM (e.g. level(L0) == 0, etc.) | no | +| `NumFiles` | num_files is the number of files in the level (gauge). | no | +| `SizeBytes` | size_bytes is the size of the level, in bytes (gauge). | no | +| `Score` | score is the compaction score of the level (gauge). | no | +| `BytesIn` | bytes_in is the number of bytes written to this level (counter). | no | +| `BytesIngested` | bytes_ingested is the number of bytes ingested into this level (counter). | no | +| `BytesMoved` | bytes_moved is the number of bytes moved into this level via a move-compaction (counter). | no | +| `BytesRead` | bytes_read is the number of bytes read from this level, during compactions (counter). | no | +| `BytesCompacted` | bytes_compacted is the number of bytes written to this level during compactions (counter). | no | +| `BytesFlushed` | bytes flushed is the number of bytes flushed to this level. This value is always zero for levels other than L0 (counter). | no | +| `TablesCompacted` | tables_compacted is the count of tables compacted into this level (counter). | no | +| `TablesFlushed` | tables_flushed is the count of tables flushed into this level (counter). | no | +| `TablesIngested` | tables_ingested is the count of tables ingested into this level (counter). | no | +| `TablesMoved` | tables_moved is the count of tables moved into this level via move-compactions (counter). | no | +| `NumSublevels` | num_sublevel is the count of sublevels for the level. This value is always zero for levels other than L0 (gauge). | no | + + + +### `store_stats` + +An event of type `store_stats` contains per store stats. + +Note that because stats are scoped to the lifetime of the process, counters +(and certain gauges) will be reset across node restarts. + + +| Field | Description | Sensitive | +|--|--|--| +| `NodeId` | node_id is the ID of the node. | no | +| `StoreId` | store_id is the ID of the store. | no | +| `Levels` | levels is a nested message containing per-level statistics. | yes | +| `CacheSize` | cache_size is the size of the cache for the store, in bytes (gauge). | no | +| `CacheCount` | cache_count is the number of items in the cache (gauge). | no | +| `CacheHits` | cache_hits is the number of cache hits (counter). | no | +| `CacheMisses` | cache_misses is the number of cache misses (counter). | no | +| `CompactionCountDefault` | compaction_count_default is the count of default compactions (counter). | no | +| `CompactionCountDeleteOnly` | compaction_count_delete_only is the count of delete-only compactions (counter). | no | +| `CompactionCountElisionOnly` | compaction_count_elision_only is the count of elision-only compactions (counter). | no | +| `CompactionCountMove` | compaction_count_move is the count of move-compactions (counter). | no | +| `CompactionCountRead` | compaction_count_read is the count of read-compactions (counter). | no | +| `CompactionCountRewrite` | compaction_count_rewrite is the count of rewrite-compactions (counter). | no | +| `CompactionNumInProgress` | compactions_num_in_progress is the number of compactions in progress (gauge). | no | +| `CompactionMarkedFiles` | compaction_marked_files is the count of files marked for compaction (gauge). | no | +| `FlushCount` | flush_count is the number of flushes (counter). | no | +| `FlushIngestCount` | | no | +| `FlushIngestTableCount` | | no | +| `FlushIngestTableBytes` | | no | +| `IngestCount` | ingest_count is the number of successful ingest operations (counter). | no | +| `MemtableSize` | memtable_size is the total size allocated to all memtables and (large) batches, in bytes (gauge). | no | +| `MemtableCount` | memtable_count is the count of memtables (gauge). | no | +| `MemtableZombieCount` | memtable_zombie_count is the count of memtables no longer referenced by the current DB state, but still in use by an iterator (gauge). | no | +| `MemtableZombieSize` | memtable_zombie_size is the size, in bytes, of all zombie memtables (gauge). | no | +| `WalLiveCount` | wal_live_count is the count of live WAL files (gauge). | no | +| `WalLiveSize` | wal_live_size is the size, in bytes, of live data in WAL files. With WAL recycling, this value is less than the actual on-disk size of the WAL files (gauge). | no | +| `WalObsoleteCount` | wal_obsolete_count is the count of obsolete WAL files (gauge). | no | +| `WalObsoleteSize` | wal_obsolete_size is the size of obsolete WAL files, in bytes (gauge). | no | +| `WalPhysicalSize` | wal_physical_size is the size, in bytes, of the WAL files on disk (gauge). | no | +| `WalBytesIn` | wal_bytes_in is the number of logical bytes written to the WAL (counter). | no | +| `WalBytesWritten` | wal_bytes_written is the number of bytes written to the WAL (counter). | no | +| `TableObsoleteCount` | table_obsolete_count is the number of tables which are no longer referenced by the current DB state or any open iterators (gauge). | no | +| `TableObsoleteSize` | table_obsolete_size is the size, in bytes, of obsolete tables (gauge). | no | +| `TableZombieCount` | table_zombie_count is the number of tables no longer referenced by the current DB state, but are still in use by an open iterator (gauge). | no | +| `TableZombieSize` | table_zombie_size is the size, in bytes, of zombie tables (gauge). | no | +| `RangeKeySetsCount` | range_key_sets_count is the approximate count of internal range key sets in the store. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## TELEMETRY + +Events in this file are related to bulk ingest operations performance metrics. + +Events in this category are logged to the `TELEMETRY` channel. + + +### `bulk_ingest_completed` + +An event of type `bulk_ingest_completed` is an event that is logged when a bulk ingest job +(restore, import, etc.) completes successfully. +It captures key performance metrics for the operation. + + +| Field | Description | Sensitive | +|--|--|--| +| `JobID` | JobID is the ID of the bulk ingest job. | no | +| `JobType` | JobType identifies the type of bulk ingest job (e.g., "restore", "import"). | no | +| `NumRows` | NumRows is the number of rows successfully ingested. | no | +| `DurationSeconds` | Duration of the ingest operation in seconds. | no | +| `DataSizeMb` | Total logical size of data ingested in megabytes. | no | +| `NodeCount` | Number of nodes that participated in the ingest operation. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Telemetry events + + + +Events in this category are logged to the `TELEMETRY` channel. + + +### `captured_index_usage_stats` + +An event of type `captured_index_usage_stats` + + +| Field | Description | Sensitive | +|--|--|--| +| `TotalReadCount` | TotalReadCount is the number of times the index has been read. | no | +| `LastRead` | LastRead is the timestamp at which the index was last read. | no | +| `TableID` | TableID is the ID of the table on which the index was created. This is same as descpb.TableID and is unique within the cluster. | no | +| `IndexID` | IndexID is the ID of the index within the scope of the given table. | no | +| `DatabaseName` | DatabaseName is the name of the database in which the index was created. | no | +| `TableName` | TableName is the name of the table on which the index was created. | no | +| `IndexName` | IndexName is the name of the index within the scope of the given table. | no | +| `IndexType` | IndexType is the type of the index. Index types include "primary" and "secondary". | no | +| `IsUnique` | IsUnique indicates if the index has a UNIQUE constraint. | no | +| `IsInverted` | IsInverted indicates if the index is an inverted index. | no | +| `CreatedAt` | CreatedAt is the timestamp at which the index was created. | no | +| `SchemaName` | SchemaName is the name of the schema in which the index was created. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `recovery_event` + +An event of type `recovery_event` is an event that is logged on every invocation of BACKUP, +RESTORE, and on every BACKUP schedule creation, with the appropriate subset +of fields populated depending on the type of event. This event is is also +logged whenever a BACKUP and RESTORE job completes or fails. + + +| Field | Description | Sensitive | +|--|--|--| +| `RecoveryType` | RecoveryType is the type of recovery described by this event, which is one of - backup - scheduled_backup - create_schedule - restore

It can also be a job event corresponding to the recovery, which is one of - backup_job - scheduled_backup_job - restore_job | no | +| `TargetScope` | TargetScope is the largest scope of the targets that the user is backing up or restoring based on the following order: table < schema < database < full cluster. | no | +| `IsMultiregionTarget` | IsMultiregionTarget is true if any of the targets contain objects with multi-region primitives. | no | +| `TargetCount` | TargetCount is the number of targets the in the BACKUP/RESTORE. | no | +| `DestinationStorageTypes` | DestinationStorageTypes are the types of storage that the user is backing up to or restoring from. | no | +| `DestinationAuthTypes` | DestinationAuthTypes are the types of authentication methods that the user is using to access the destination storage. | no | +| `IsLocalityAware` | IsLocalityAware indicates if the BACKUP or RESTORE is locality aware. | no | +| `WithRevisionHistory` | WithRevisionHistory is true if the BACKUP includes revision history. | no | +| `HasEncryptionPassphrase` | HasEncryptionPassphrase is true if the user provided an encryption passphrase to encrypt/decrypt their backup. | no | +| `KMSType` | KMSType is the type of KMS the user is using to encrypt/decrypt their backup. | no | +| `KMSCount` | KMSCount is the number of KMS the user is using. | no | +| `Options` | Options contain all the names of the options specified by the user in the BACKUP or RESTORE statement. For options that are accompanied by a value, only those with non-empty values will be present.

It's important to note that there are no option values anywhere in the event payload. Future changes to telemetry should refrain from adding values to the payload unless they are properly redacted. | no | +| `JobID` | JobID is the ID of the BACKUP/RESTORE job. | no | +| `ResultStatus` | ResultStatus indicates whether the job succeeded or failed. | no | +| `ErrorText` | ErrorText is the text of the error that caused the job to fail. | partially | +| `RecurringCron` | RecurringCron is the crontab for the incremental backup. | no | +| `FullBackupCron` | FullBackupCron is the crontab for the full backup. | no | +| `CustomFirstRunTime` | CustomFirstRunTime is the timestamp for the user configured first run time. Expressed as nanoseconds since the Unix epoch. | no | +| `IgnoreExistingBackup` | IgnoreExistingBackup is true iff the BACKUP schedule should still be created even if a backup is already present in its destination. | no | +| `ApplicationName` | The application name for the session where recovery event was created. | no | +| `NumRows` | NumRows is the number of rows successfully imported, backed up or restored. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_descriptor` + +An event of type `schema_descriptor` is an event for schema telemetry, whose purpose is +to take periodic snapshots of the cluster's SQL schema and publish them in +the telemetry log channel. For all intents and purposes, the data in such a +snapshot can be thought of the outer join of certain system tables: +namespace, descriptor, and at some point perhaps zones, etc. + +Snapshots are too large to conveniently be published as a single log event, +so instead they're broken down into SchemaDescriptor events which +contain the data in one record of this outer join projection. These events +are prefixed by a header (a SchemaSnapshotMetadata event). + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of the snapshot that this event is part of. | no | +| `ParentDatabaseID` | ParentDatabaseID matches the same key column in system.namespace. | no | +| `ParentSchemaID` | ParentSchemaID matches the same key column in system.namespace. | no | +| `Name` | Name matches the same key column in system.namespace. | no | +| `DescID` | DescID matches the 'id' column in system.namespace and system.descriptor. | no | +| `Desc` | Desc matches the 'descriptor' column in system.descriptor. Some contents of the descriptor may be redacted to prevent leaking PII. | no | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +### `schema_snapshot_metadata` + +An event of type `schema_snapshot_metadata` is an event describing a schema snapshot, which +is a set of SchemaDescriptor messages sharing the same SnapshotID. + + +| Field | Description | Sensitive | +|--|--|--| +| `SnapshotID` | SnapshotID is the unique identifier of this snapshot. | no | +| `NumRecords` | NumRecords is how many SchemaDescriptor events are in the snapshot. | no | +| `AsOfTimestamp` | AsOfTimestamp is when the snapshot was taken. This is equivalent to the timestamp given in the AS OF SYSTEM TIME clause when querying the namespace and descriptor tables in the system database. Expressed as nanoseconds since the Unix epoch. | no | +| `Errors` | Errors records any errors encountered when post-processing this snapshot, which includes the redaction of any potential PII. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | + +## Zone config events + +Events in this category pertain to zone configuration changes on +the SQL schema or system ranges. + +When zone configs apply to individual tables or other objects in a +SQL logical schema, they are relative to a particular SQL tenant. +In a multi-tenant setup, copies of these zone config events are preserved +in each tenant's own `system.eventlog` table. + +When they apply to cluster-level ranges (e.g., the system zone config), +they are stored in the system tenant's own `system.eventlog` table. + +Events in this category are logged to the `OPS` channel. + + +### `remove_zone_config` + +An event of type `remove_zone_config` is recorded when a zone config is removed. + + + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + +### `set_zone_config` + +An event of type `set_zone_config` is recorded when a zone config is changed. + + +| Field | Description | Sensitive | +|--|--|--| +| `ResolvedOldConfig` | The string representation of the resolved old zone config. This is not necessarily the same as the zone config that was previously set -- as it includes the resolved values of the zone config options. In other words, a zone config that hasn't been properly "set" yet (and inherits from its parent) will have a resolved_old_config that has details of the values it inherits from its parent. This is particularly useful to get a proper diff between the old and new zone config. | yes | + + +#### Common fields + +| Field | Description | Sensitive | +|--|--|--| +| `Timestamp` | The timestamp of the event. Expressed as nanoseconds since the Unix epoch. | no | +| `EventType` | The type of the event. | no | +| `Statement` | A normalized copy of the SQL statement that triggered the event. The statement string contains a mix of sensitive and non-sensitive details (it is redactable). | partially | +| `Tag` | The statement tag. This is separate from the statement string, since the statement string can contain sensitive information. The tag is guaranteed not to. | no | +| `User` | The user account that triggered the event. The special usernames `root` and `node` are not considered sensitive. | depends | +| `DescriptorID` | The primary object descriptor affected by the operation. Set to zero for operations that don't affect descriptors. | no | +| `ApplicationName` | The application name for the session where the event was emitted. This is included in the event to ease filtering of logging output by application. | no | +| `PlaceholderValues` | The mapping of SQL placeholders to their values, for prepared statements. | yes | +| `TxnReadTimestamp` | The current read timestamp of the transaction that triggered the event, if in a transaction. | no | +| `Target` | The target object of the zone config change. | yes | +| `Config` | The applied zone config in YAML format. | yes | +| `Options` | The SQL representation of the applied zone config options. | yes | + + + + +## Enumeration types + +### `AuthFailReason` + +AuthFailReason is the inventory of possible reasons for an +authentication failure. + + +| Value | Textual alias in code or documentation | Description | +|--|--|--| +| 0 | UNKNOWN | is reported when the reason is unknown. | +| 1 | USER_RETRIEVAL_ERROR | occurs when there was an internal error accessing the principals. | +| 2 | USER_NOT_FOUND | occurs when the principal is unknown. | +| 3 | LOGIN_DISABLED | occurs when the user does not have LOGIN privileges. | +| 4 | METHOD_NOT_FOUND | occurs when no HBA rule matches or the method does not exist. | +| 5 | PRE_HOOK_ERROR | occurs when the authentication handshake encountered a protocol error. | +| 6 | CREDENTIALS_INVALID | occurs when the client-provided credentials were invalid. | +| 7 | CREDENTIALS_EXPIRED | occur when the credentials provided by the client are expired. | +| 8 | NO_REPLICATION_ROLEOPTION | occurs when the connection requires a replication role option, but the user does not have it. | +| 9 | AUTHORIZATION_ERROR | is used for errors during the authorization phase. For example, this would include issues with mapping LDAP groups to SQL roles and granting those roles to the user. | +| 10 | PROVISIONING_ERROR | is used for errors during the user provisioning phase. This would include errors when the transaction to provision the authenticating user failed to execute. | + + + diff --git a/src/current/_includes/cockroach-generated/release-26.2/logformats.md b/src/current/_includes/cockroach-generated/release-26.2/logformats.md new file mode 100644 index 00000000000..89580c9fc15 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-26.2/logformats.md @@ -0,0 +1,382 @@ + +The supported log output formats are documented below. + + +- [`crdb-v1`](#format-crdb-v1) + +- [`crdb-v1-count`](#format-crdb-v1-count) + +- [`crdb-v1-tty`](#format-crdb-v1-tty) + +- [`crdb-v1-tty-count`](#format-crdb-v1-tty-count) + +- [`crdb-v2`](#format-crdb-v2) + +- [`crdb-v2-tty`](#format-crdb-v2-tty) + +- [`json`](#format-json) + +- [`json-compact`](#format-json-compact) + +- [`json-fluent`](#format-json-fluent) + +- [`json-fluent-compact`](#format-json-fluent-compact) + + + +## Format `crdb-v1` + + +This is a legacy file format used from CockroachDB v1.0. + +Each log entry is emitted using a common prefix, described below, followed by: + +- The logging context tags enclosed between `[` and `]`, if any. It is possible + for this to be omitted if there were no context tags. +- Optionally, a counter column, if the option 'show-counter' is enabled. See below for details. +- the text of the log entry. + +Beware that the text of the log entry can span multiple lines. +The following caveats apply: + +- The text of the log entry can start with text enclosed between `[` and `]`. + If there were no logging tags to start with, it is not possible to distinguish between + logging context tag information and a `[...]` string in the main text of the + log entry. This means that this format is ambiguous. + + To remove this ambiguity, you can use the option 'show-counter'. + +- The text of the log entry can embed arbitrary application-level strings, + including strings that represent log entries. In particular, an accident + of implementation can cause the common entry prefix (described below) + to also appear on a line of its own, as part of the payload of a previous + log entry. There is no automated way to recognize when this occurs. + Care must be taken by a human observer to recognize these situations. + +- The log entry parser provided by CockroachDB to read log files is faulty + and is unable to recognize the aforementioned pitfall; nor can it read + entries larger than 64KiB successfully. Generally, use of this internal + log entry parser is discouraged for entries written with this format. + +See the newer format `crdb-v2` for an alternative +without these limitations. + +### Header lines + +At the beginning of each file, a header is printed using a similar format as +regular log entries. This header reports when the file was created, +which parameters were used to start the server, the server identifiers +if known, and other metadata about the running process. + +- This header appears to be logged at severity `INFO` (with an `I` prefix + at the start of the line) even though it does not really have a severity. +- The header is printed unconditionally even when a filter is configured to + omit entries at the `INFO` level. + +### Common log entry prefix + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker tags counter + +Reminder, the tags may be omitted; and the counter is only printed if the option +'show-counter' is specified. + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (omitted if zero for use by tests). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. | +| line | The line number where the entry originated. | +| marker | Redactability marker ` + redactableIndicator + ` (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. May be absent. | +| counter | The entry counter. Only included if 'show-counter' is enabled. | + +The redactability marker can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. + +If the marker ` + redactableIndicator + ` is present, the remainder of the log entry +contains delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `show-counter` | Whether to include the counter column in the line header. Without it, the format may be ambiguous due to the optionality of tags. | +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v1-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: none` + + +## Format `crdb-v1-tty` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: false` +- `colors: auto` + + +## Format `crdb-v1-tty-count` + +This format name is an alias for 'crdb-v1' with +the following format option defaults: + +- `show-counter: true` +- `colors: auto` + + +## Format `crdb-v2` + +This is the main file format used from CockroachDB v21.1. + +Each log entry is emitted using a common prefix, described below, +followed by the text of the log entry. + +### Entry format + +Each line of output starts with the following prefix: + + Lyymmdd hh:mm:ss.uuuuuu goid [chan@]file:line marker [tags...] counter cont + +| Field | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------| +| L | A single character, representing the [log level](logging.html#logging-levels-severities) (e.g., `I` for `INFO`). | +| yy | The year (zero padded; i.e., 2016 is `16`). | +| mm | The month (zero padded; i.e., May is `05`). | +| dd | The day (zero padded). | +| hh:mm:ss.uuuuuu | Time in hours, minutes and fractional seconds. Timezone is UTC. | +| goid | The goroutine id (zero when cannot be determined). | +| chan | The channel number (omitted if zero for backward compatibility). | +| file | The file name where the entry originated. Also see below. | +| line | The line number where the entry originated. | +| marker | Redactability marker "⋮" (see below for details). | +| tags | The logging tags, enclosed between `[` and `]`. See below. | +| counter | The optional entry counter (see below for details). | +| cont | Continuation mark for structured and multi-line entries. See below. | + +The `chan@` prefix before the file name indicates the logging channel, +and is omitted if the channel is `DEV`. + +The file name may be prefixed by the string `(gostd) ` to indicate +that the log entry was produced inside the Go standard library, instead +of a CockroachDB component. Entry parsers must be configured to ignore this prefix +when present. + +`marker` can be empty; in this case, its position in the common prefix is +a double ASCII space character which can be used to reliably identify this situation. +If the marker "⋮" is present, the remainder of the log entry +contains delimiters (‹...›) +around fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +when log redaction is requested. + +The logging `tags` are enclosed between square brackets `[...]`, +and the syntax `[-]` is used when there are no logging tags +associated with the log entry. + +`counter` is numeric, and is incremented for every +log entry emitted to this sink. (There is thus one counter sequence per +sink.) For entries that do not have a counter value +associated (e.g., header entries in file sinks), the counter position +in the common prefix is empty: `tags` is then +followed by two ASCII space characters, instead of one space; the `counter`, +and another space. The presence of the two ASCII spaces indicates +reliably that no counter was present. + +`cont` is a format/continuation indicator: + +| Continuation indicator | ASCII | Description | +|------------------------|-------|--| +| space | 0x32 | Start of an unstructured entry. | +| equal sign, "=" | 0x3d | Start of a structured entry. | +| exclamation mark, "!" | 0x21 | Start of an embedded stack trace. | +| plus sign, "+" | 0x2b | Continuation of a multi-line entry. The payload contains a newline character at this position. | +| vertical bar | 0x7c | Continuation of a large entry. | + +### Examples + +Example single-line unstructured entry: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 started with engine type ‹2› +~~~ + +Example multi-line unstructured entry: + +~~~ +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 node startup completed: +I210116 21:49:17.083093 14 1@cli/start.go:690 ⋮ [-] 40 +CockroachDB node starting at 2021-01-16 21:49 (took 0.0s) +~~~ + +Example structured entry: + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventType":"node_restart"} +~~~ + +Example long entries broken up into multiple lines: + +~~~ +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.... +I210116 21:49:17.073282 14 server/node.go:464 ⋮ [-] 23 |aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +~~~ + +~~~ +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 ={"Timestamp":1610833757080706620,"EventTy... +I210116 21:49:17.080713 14 1@util/log/event_log.go:32 ⋮ [-] 32 |pe":"node_restart"} +~~~ + +### Backward-compatibility notes + +Entries in this format can be read by most `crdb-v1` log parsers, +in particular the one included in the DB console and +also the [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) +facility. + +However, implementers of previous version parsers must +understand that the logging tags field is now always +included, and the lack of logging tags is included +by a tag string set to `[-]`. + +Likewise, the entry counter is now also always included, +and there is a special character after `counter` +to indicate whether the remainder of the line is a +structured entry, or a continuation of a previous entry. + +Finally, in the previous format, structured entries +were prefixed with the string `Structured entry: `. In +the new format, they are prefixed by the `=` continuation +indicator. + + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `colors` | The color profile to use. Possible values: none, auto, ansi, 256color. Default is auto. | +| `timezone` | The timezone to use for the timestamp column. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | + + + +## Format `crdb-v2-tty` + +This format name is an alias for 'crdb-v2' with +the following format option defaults: + +- `colors: auto` + + +## Format `json` + +This format emits log entries as a JSON payload. + +The JSON object is guaranteed to not contain unescaped newlines +or other special characters, and the entry as a whole is followed +by a newline character. This makes the format suitable for +processing over a stream unambiguously. + +Each entry contains at least the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `tag` | `tag` | (Only if the option `fluent-tag: true` is given.) A Fluent tag for the event, formed by the process name and the logging channel. | +| `d` | `datetime` | The pretty-printed date/time of the event timestamp, if enabled via options. | +| `f` | `file` | The name of the source file where the event was emitted. | +| `g` | `goroutine` | The identifier of the goroutine where the event was emitted. | +| `l` | `line` | The line number where the event was emitted in the source. | +| `r` | `redactable` | Whether the payload is redactable (see below for details). | +| `t` | `timestamp` | The timestamp at which the event was emitted on the logging channel. | +| `v` | `version` | The binary version with which the event was generated. | + + +After a couple of *header* entries written at the beginning of each log sink, +all subsequent log entries also contain the following fields: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `C` | `channel` | The name of the logging channel where the event was sent. | +| `sev` | `severity` | The severity of the event. | +| `c` | `channel_numeric` | The numeric identifier for the logging channel where the event was sent. | +| `n` | `entry_counter` | The entry number on this logging sink, relative to the last process restart. | +| `s` | `severity_numeric` | The numeric value of the severity of the event. | + + +Additionally, the following fields are conditionally present: + +| Field name if `tag-style: compact` is specified | Field name if `tag-style: verbose` is specified | Description | +|-------|-------|-------------| +| `N` | `node_id` | The node ID where the event was generated, once known. Only reported for single-tenant or KV servers. | +| `x` | `cluster_id` | The cluster ID where the event was generated, once known. Only reported for single-tenant of KV servers. | +| `q` | `instance_id` | The SQL instance ID where the event was generated, once known. | +| `T` | `tenant_id` | The SQL tenant ID where the event was generated, once known. | +| `V` | `tenant_name` | The SQL virtual cluster where the event was generated, once known. | +| `tags` | `tags` | The logging context tags for the entry, if there were context tags. | +| `message` | `message` | For unstructured events, the flat text payload. | +| `event` | `event` | The logging event, if structured (see below for details). | +| `stacks` | `stacks` | Goroutine stacks, for fatal events. | + +When an entry is structured, the `event` field maps to a dictionary +whose structure is one of the documented structured events. See the [reference documentation](eventlog.html) +for structured events for a list of possible payloads. + +When the entry is marked as `redactable`, the `tags`, `message`, and/or `event` payloads +contain delimiters (‹...›) around +fields that are considered sensitive. These markers are automatically recognized +by [`cockroach debug zip`](cockroach-debug-zip.html) and [`cockroach debug merge-logs`](cockroach-debug-merge-logs.html) when log redaction is requested. + +Additional options recognized via `format-options`: + +| Option | Description | +|--------|-------------| +| `datetime-format` | The format to use for the `datetime` field. The value can be one of `none`, `iso8601`/`rfc3339` (synonyms), or `rfc1123`. Default is `none`. | +| `datetime-timezone` | The timezone to use for the `datetime` field. The value can be any timezone name recognized by the Go standard library. Default is `UTC` | +| `tag-style` | The tags to include in the envelope. The value can be `compact` (one letter tags) or `verbose` (long-form tags). Default is `verbose`. | +| `fluent-tag` | Whether to produce an additional field called `tag` for Fluent compatibility. Default is `false`. | + + + +## Format `json-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: false` +- `tag-style: compact` + + +## Format `json-fluent` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: verbose` + + +## Format `json-fluent-compact` + +This format name is an alias for 'json' with +the following format option defaults: + +- `fluent-tag: true` +- `tag-style: compact` + + diff --git a/src/current/_includes/cockroach-generated/release-26.2/logging.md b/src/current/_includes/cockroach-generated/release-26.2/logging.md new file mode 100644 index 00000000000..7661187987e --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-26.2/logging.md @@ -0,0 +1,188 @@ +## Logging levels (severities) + +### INFO + +The `INFO` severity is used for informational messages that do not +require action. + +### WARNING + +The `WARNING` severity is used for situations which may require special handling, +where normal operation is expected to resume automatically. + +### ERROR + +The `ERROR` severity is used for situations that require special handling, +where normal operation could not proceed as expected. +Other operations can continue mostly unaffected. + +### FATAL + +The `FATAL` severity is used for situations that require an immedate, hard +server shutdown. A report is also sent to telemetry if telemetry +is enabled. + + +## Logging channels + +### `DEV` + +The `DEV` channel is used during development to collect log +details useful for troubleshooting that fall outside the +scope of other channels. It is also the default logging +channel for events not associated with a channel. + +This channel is special in that there are no constraints as to +what may or may not be logged on it. Conversely, users in +production deployments are invited to not collect `DEV` logs in +centralized logging facilities, because they likely contain +sensitive operational data. +See [Configure logs](configure-logs.html#dev-channel). + +### `OPS` + +The `OPS` channel is used to report "point" operational events, +initiated by user operators or automation: + + - Operator or system actions on server processes: process starts, + stops, shutdowns, crashes (if they can be logged), + including each time: command-line parameters, current version being run + - Actions that impact the topology of a cluster: node additions, + removals, decommissions, etc. + - Job-related initiation or termination + - [Cluster setting](cluster-settings.html) changes + - [Zone configuration](configure-replication-zones.html) changes + +### `HEALTH` + +The `HEALTH` channel is used to report "background" operational +events, initiated by CockroachDB or reporting on automatic processes: + + - Current resource usage, including critical resource usage + - Node-node connection events, including connection errors and + gossip details + - Range and table leasing events + - Up- and down-replication, range unavailability + +### `STORAGE` + +The `STORAGE` channel is used to report low-level storage +layer events (RocksDB/Pebble). + +### `SESSIONS` + +The `SESSIONS` channel is used to report client network activity when enabled via +the `server.auth_log.sql_connections.enabled` and/or +`server.auth_log.sql_sessions.enabled` [cluster setting](cluster-settings.html): + + - Connections opened/closed + - Authentication events: logins, failed attempts + - Session and query cancellation + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_SCHEMA` + +The `SQL_SCHEMA` channel is used to report changes to the +SQL logical schema, excluding privilege and ownership changes +(which are reported separately on the `PRIVILEGES` channel) and +zone configuration changes (which go to the `OPS` channel). + +This includes: + + - Database/schema/table/sequence/view/type creation + - Adding/removing/changing table columns + - Changing sequence parameters + +`SQL_SCHEMA` events generally comprise changes to the schema that affect the +functional behavior of client apps using stored objects. + +### `USER_ADMIN` + +The `USER_ADMIN` channel is used to report changes +in users and roles, including: + + - Users added/dropped + - Changes to authentication credentials (e.g., passwords, validity, etc.) + - Role grants/revocations + - Role option grants/revocations + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `PRIVILEGES` + +The `PRIVILEGES` channel is used to report data +authorization changes, including: + + - Privilege grants/revocations on database, objects, etc. + - Object ownership changes + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SENSITIVE_ACCESS` + +The `SENSITIVE_ACCESS` channel is used to report SQL +data access to sensitive data: + + - Data access audit events (when table audit is enabled via + [ALTER TABLE ... EXPERIMENTAL_AUDIT](alter-table.html#experimental_audit)) + - Data access audit events (when role-based audit is enabled via + [`sql.log.user_audit` cluster setting](role-based-audit-logging.html#syntax-of-audit-settings)) + - SQL statements executed by users with the admin role + - Operations that write to system tables + +This is typically configured in "audit" mode, with event +numbering and synchronous writes. + +### `SQL_EXEC` + +The `SQL_EXEC` channel is used to report SQL execution on +behalf of client connections: + + - Logical SQL statement executions (when enabled via the + `sql.log.all_statements.enabled` [cluster setting](cluster-settings.html)) + - uncaught Go panic errors during the execution of a SQL statement. + +### `SQL_PERF` + +The `SQL_PERF` channel is used to report SQL executions +that are marked as "out of the ordinary" +to facilitate performance investigations. +This includes the SQL "slow query log". + +Arguably, this channel overlaps with `SQL_EXEC`. +However, we keep both channels separate for backward compatibility +with versions prior to v21.1, where the corresponding events +were redirected to separate files. + +### `SQL_INTERNAL_PERF` + +The `SQL_INTERNAL_PERF` channel is like the `SQL_PERF` channel, but is aimed at +helping developers of CockroachDB itself. It exists as a separate +channel so as to not pollute the `SQL_PERF` logging output with +internal troubleshooting details. + +### `TELEMETRY` + +The `TELEMETRY` channel reports telemetry events. Telemetry events describe +feature usage within CockroachDB and anonymizes any application- +specific data. + +### `KV_DISTRIBUTION` + +The `KV_DISTRIBUTION` channel is used to report data distribution events, such as moving +replicas between stores in the cluster, or adding (removing) replicas to +ranges. + +### `CHANGEFEED` + +The `CHANGEFEED` channel is used to report changefeed events + +### `KV_EXEC` + +The `KV_EXEC` channel is used to report KV execution events that don't fall into the +KV_DISTRIBUTION channel. + diff --git a/src/current/_includes/cockroach-generated/release-26.2/settings/settings.html b/src/current/_includes/cockroach-generated/release-26.2/settings/settings.html new file mode 100644 index 00000000000..9a6fb50965d --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-26.2/settings/settings.html @@ -0,0 +1,411 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingTypeDefaultDescriptionSupported Deployments
admission.disk_bandwidth_tokens.elastic.enabled
booleantruewhen true, and provisioned bandwidth for the disk corresponding to a store is configured, tokens for elastic work will be limited if disk bandwidth becomes a bottleneckAdvanced/Self-Hosted
admission.epoch_lifo.enabled
booleanfalsewhen true, epoch-LIFO behavior is enabled when there is significant delay in admissionBasic/Standard/Advanced/Self-Hosted
admission.epoch_lifo.epoch_closing_delta_duration
duration5msthe delta duration before closing an epoch, for epoch-LIFO admission control orderingBasic/Standard/Advanced/Self-Hosted
admission.epoch_lifo.epoch_duration
duration100msthe duration of an epoch, for epoch-LIFO admission control orderingBasic/Standard/Advanced/Self-Hosted
admission.epoch_lifo.queue_delay_threshold_to_switch_to_lifo
duration105msthe queue delay encountered by a (tenant,priority) for switching to epoch-LIFO orderingBasic/Standard/Advanced/Self-Hosted
admission.kv.enabled
booleantruewhen true, work performed by the KV layer is subject to admission controlAdvanced/Self-Hosted
admission.sql_kv_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a KV response is subject to admission controlBasic/Standard/Advanced/Self-Hosted
admission.sql_sql_response.enabled
booleantruewhen true, work performed by the SQL layer when receiving a DistSQL response is subject to admission controlBasic/Standard/Advanced/Self-Hosted
bulkio.backup.file_size
byte size128 MiBtarget size for individual data files produced during BACKUPBasic/Standard/Advanced/Self-Hosted
bulkio.backup.read_timeout
duration5m0samount of time after which a read attempt is considered timed out, which causes the backup to failBasic/Standard/Advanced/Self-Hosted
bulkio.backup.read_with_priority_after
duration1m0samount of time since the read-as-of time above which a BACKUP should use priority when retrying readsBasic/Standard/Advanced/Self-Hosted
bulkio.import.row_count_validation.mode
(alias: bulkio.import.row_count_validation.unsafe.mode)
enumerationoffcontrols validation of imported data via INSPECT jobs. Options: 'off' (no validation), 'async' (background validation), 'sync' (blocking validation). If disabled, IMPORT will not perform a post-import row count check. [off = 0, async = 1, sync = 2]Basic/Standard/Advanced/Self-Hosted
bulkio.merge.file_size
byte size1.0 GiBtarget size for individual data files produced during local only merge phasesBasic/Standard/Advanced/Self-Hosted
physical_replication.consumer.minimum_flush_interval
(alias: bulkio.stream_ingestion.minimum_flush_interval)
duration5sthe minimum timestamp between flushes; flushes may still occur if internal buffers fill upAdvanced/Self-Hosted
changefeed.aggregator.flush_jitter
float0.1jitter aggregator flushes as a fraction of min_checkpoint_frequency. This setting has no effect if min_checkpoint_frequency is set to 0.Basic/Standard/Advanced/Self-Hosted
changefeed.backfill.concurrent_scan_requests
integer0number of concurrent scan requests per node issued during a backfillBasic/Standard/Advanced/Self-Hosted
changefeed.backfill.scan_request_size
integer524288the maximum number of bytes returned by each scan requestBasic/Standard/Advanced/Self-Hosted
changefeed.batch_reduction_retry.enabled
(alias: changefeed.batch_reduction_retry_enabled)
booleanfalseif true, kafka changefeeds upon erroring on an oversized batch will attempt to resend the messages with progressively lower batch sizesBasic/Standard/Advanced/Self-Hosted
changefeed.default_range_distribution_strategy
enumerationdefaultcontrols how changefeed work is distributed across nodes. 'default' defers to DistSQL for node selection and work distribution. 'balanced_simple' uses DistSQL for node selection but then attempts to evenly distribute ranges across those selected nodes for better load balancing. this setting does not override locality restrictions and can be overridden per-changefeed using the 'range_distribution_strategy' option. [default = 0, balanced_simple = 1]Basic/Standard/Advanced/Self-Hosted
changefeed.event_consumer_worker_queue_size
integer16if changefeed.event_consumer_workers is enabled, this setting sets the maxmimum number of events which a worker can bufferBasic/Standard/Advanced/Self-Hosted
changefeed.event_consumer_workers
integer0the number of workers to use when processing events: <0 disables, 0 assigns a reasonable default, >0 assigns the setting value. for experimental/core changefeeds and changefeeds using parquet format, this is disabledBasic/Standard/Advanced/Self-Hosted
changefeed.fast_gzip.enabled
booleantrueuse fast gzip implementationBasic/Standard/Advanced/Self-Hosted
changefeed.span_checkpoint.lag_threshold
(alias: changefeed.frontier_highwater_lag_checkpoint_threshold)
duration10m0sthe amount of time a changefeed's lagging (slowest) spans must lag behind its leading (fastest) spans before a span-level checkpoint to save leading span progress is written; if 0, span-level checkpoints due to lagging spans is disabledBasic/Standard/Advanced/Self-Hosted
changefeed.kafka.max_request_size
byte size256 MiBthe maximum number of uncompressed bytes sent in a single request to a Kafka broker; lowering this value helps avoid spurious "message too large" errors that can occur when multiple messages are combined into a single batch; this setting is overridden by the per-changefeed Flush { MaxBytes: <int> } optionBasic/Standard/Advanced/Self-Hosted
changefeed.kafka_v2_error_details.enabled
booleantrueif enabled, Kafka v2 sinks will include the message key, size, and MVCC timestamp in message too large errorsBasic/Standard/Advanced/Self-Hosted
changefeed.memory.per_changefeed_limit
byte size512 MiBcontrols amount of data that can be buffered per changefeedBasic/Standard/Advanced/Self-Hosted
changefeed.resolved_timestamp.min_update_interval
(alias: changefeed.min_highwater_advance)
duration0sminimum amount of time that must have elapsed since the last time a changefeed's resolved timestamp was updated before it is eligible to be updated again; default of 0 means no minimum interval is enforced but updating will still be limited by the average time it takes to checkpoint progressBasic/Standard/Advanced/Self-Hosted
changefeed.node_throttle_config
stringspecifies node level throttling configuration for all changefeeedsBasic/Standard/Advanced/Self-Hosted
changefeed.partition_alg.enabled
booleanfalseif enabled, allows specifying the partition_alg changefeed option to choose between fnv-1a (default) and murmur2 hash functions for Kafka partitioning. Only affects changefeeds using a kafka sink with changefeed.new_kafka_sink_enabled set to true.Basic/Standard/Advanced/Self-Hosted
changefeed.progress.frontier_persistence.interval
duration30sminimum amount of time that must elapse before a changefeed will persist its entire span frontier againBasic/Standard/Advanced/Self-Hosted
changefeed.protect_timestamp.max_age
duration96h0m0sfail the changefeed if the protected timestamp age exceeds this threshold; 0 disables expirationBasic/Standard/Advanced/Self-Hosted
changefeed.protect_timestamp_interval
duration10m0scontrols how often the changefeed forwards its protected timestamp to the resolved timestampBasic/Standard/Advanced/Self-Hosted
changefeed.schema_feed.read_with_priority_after
duration1m0sretry with high priority if we were not able to read descriptors for too long; 0 disablesBasic/Standard/Advanced/Self-Hosted
changefeed.sink_io_workers
integer0the number of workers used by changefeeds when sending requests to the sink (currently the batching versions of webhook, pubsub, and kafka sinks that are enabled by changefeed.new_<sink type>_sink_enabled only): <0 disables, 0 assigns a reasonable default, >0 assigns the setting valueBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.concurrent_upload_buffers
integer1controls the number of concurrent buffers that will be used by the Azure client when uploading chunks.Each buffer can buffer up to cloudstorage.write_chunk.size of memory during an uploadBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.azure.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.gs.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.gs.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.gs.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.gs.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.custom_ca
stringcustom root CA (appended to system's default CAs) for verifying certificates when interacting with HTTPS storageBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.http.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nodelocal.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nodelocal.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nodelocal.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nodelocal.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nullsink.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nullsink.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nullsink.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.nullsink.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.s3.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.s3.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.s3.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.s3.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.timeout
duration10m0sthe timeout for import/export storage operationsBasic/Standard/Advanced/Self-Hosted
cloudstorage.userfile.read.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.userfile.read.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.userfile.write.node_burst_limit
byte size0 Bburst limit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cloudstorage.userfile.write.node_rate_limit
byte size0 Blimit on number of bytes per second per node across operations writing to the designated cloud storage provider if non-zeroBasic/Standard/Advanced/Self-Hosted
cluster.auto_upgrade.enabled
booleantruedisable automatic cluster version upgrade until resetBasic/Standard/Advanced/Self-Hosted
cluster.organization
stringorganization nameAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
cluster.preserve_downgrade_option
stringdisable (automatic or manual) cluster version upgrade from the specified version until resetBasic/Standard/Advanced/Self-Hosted
debug.zip.redact_addresses.enabled
booleanfalseenables the redaction of hostnames and ip addresses in debug zipBasic/Standard/Advanced/Self-Hosted
diagnostics.active_query_dumps.enabled
booleantrueexperimental: enable dumping of anonymized active queries to disk when node is under memory pressureAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
diagnostics.forced_sql_stat_reset.interval
duration2h0m0sinterval after which the reported SQL Stats are reset even if not collected by telemetry reporter. It has a max value of 24H.Basic/Standard/Advanced/Self-Hosted
diagnostics.memory_monitoring_dumps.enabled
booleantrueenable dumping of memory monitoring state at the same time as heap profiles are takenAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
diagnostics.reporting.enabled
booleantrueenable reporting diagnostic metrics to cockroach labs, but is ignored for Trial or Free licensesBasic/Standard/Advanced/Self-Hosted
diagnostics.reporting.interval
duration1h0m0sinterval at which diagnostics data should be reportedBasic/Standard/Advanced/Self-Hosted
enterprise.license
stringthe encoded cluster licenseAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
external.graphite.endpoint
stringif nonempty, push server metrics to the Graphite or Carbon server at the specified host:portBasic/Standard/Advanced/Self-Hosted
external.graphite.interval
duration10sthe interval at which metrics are pushed to Graphite (if enabled)Basic/Standard/Advanced/Self-Hosted
feature.backup.enabled
booleantrueset to true to enable backups, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.changefeed.enabled
booleantrueset to true to enable changefeeds, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.export.enabled
booleantrueset to true to enable exports, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.import.enabled
booleantrueset to true to enable imports, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.infer_rbr_region_col_using_constraint.enabled
booleanfalseset to true to enable looking up the region column via a foreign key constraint in a REGIONAL BY ROW table, false to disable; default is falseBasic/Standard/Advanced/Self-Hosted
feature.restore.enabled
booleantrueset to true to enable restore, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.schema_change.enabled
booleantrueset to true to enable schema changes, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.stats.enabled
booleantrueset to true to enable CREATE STATISTICS/ANALYZE, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
feature.vector_index.enabled
booleantrueset to true to enable vector indexes, false to disable; default is trueBasic/Standard/Advanced/Self-Hosted
jobs.retention_time
duration336h0m0sthe amount of time for which records for completed jobs are retainedBasic/Standard/Advanced/Self-Hosted
kv.allocator.lease_rebalance_threshold
float0.05minimum fraction away from the mean a store's lease count can be before it is considered for lease-transfersAdvanced/Self-Hosted
kv.allocator.load_based_lease_rebalancing.enabled
booleantrueset to enable rebalancing of range leases based on load and latency; has no effect when kv.allocator.load_based_rebalancing is set to 'multi-metric only' or 'multi-metric and count'Advanced/Self-Hosted
kv.allocator.load_based_rebalancing
enumerationleases and replicaswhether to rebalance based on the distribution of load across stores [off = 0, leases = 1, leases and replicas = 2, multi-metric only = 3, multi-metric and count = 4]Advanced/Self-Hosted
kv.allocator.load_based_rebalancing.objective
enumerationcpuwhat objective does the cluster use to rebalance; if set to `qps` the cluster will attempt to balance qps among stores, if set to `cpu` the cluster will attempt to balance cpu usage among stores [qps = 0, cpu = 1]Advanced/Self-Hosted
kv.allocator.load_based_rebalancing_interval
duration1m0sthe rough interval at which each store will check for load-based lease / replica rebalancing opportunitiesAdvanced/Self-Hosted
kv.allocator.qps_rebalance_threshold
float0.1minimum fraction away from the mean a store's QPS (such as queries per second) can be before it is considered overfull or underfullAdvanced/Self-Hosted
kv.allocator.range_rebalance_threshold
float0.05minimum fraction away from the mean a store's range count can be before it is considered overfull or underfullAdvanced/Self-Hosted
kv.allocator.store_cpu_rebalance_threshold
float0.1minimum fraction away from the mean a store's cpu usage can be before it is considered overfull or underfullAdvanced/Self-Hosted
kv.bulk_io_write.max_rate
byte size1.0 TiBthe rate limit (bytes/sec) to use for writes to disk on behalf of bulk io opsAdvanced/Self-Hosted
kv.bulk_io_write.min_capacity_remaining_fraction
float0.05remaining store capacity fraction below which bulk ingestion requests are rejectedAdvanced/Self-Hosted
kv.bulk_sst.max_allowed_overage
byte size64 MiBif positive, allowed size in excess of target size for SSTs from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryAdvanced/Self-Hosted
kv.bulk_sst.target_size
byte size16 MiBtarget size for SSTs emitted from export requests; export requests (i.e. BACKUP) may buffer up to the sum of kv.bulk_sst.target_size and kv.bulk_sst.max_allowed_overage in memoryAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.follower_reads.enabled
(alias: kv.closed_timestamp.follower_reads_enabled)
booleantrueallow (all) replicas to serve consistent historical reads based on closed timestamp informationAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.lead_for_global_reads_auto_tune.enabled
booleanfalseif enabled, observed network latency between leaseholders and their furthest follower will be used to adjust closed timestamp policies for rangesranges configured to serve global reads. kv.closed_timestamp.lead_for_global_reads_override takes precedence if set.Advanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.lead_for_global_reads_override
duration0sif nonzero, overrides the lead time that global_read ranges use to publish closed timestampsAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.side_transport_interval
duration200msthe interval at which the closed timestamp side-transport attempts to advance each range's closed timestamp; set to 0 to disable the side-transportAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.side_transport_pacing_refresh_interval
duration10msthe refresh interval for the task pacer that controls pacing of sending sidetransport updates to avoid overloading the system when many connections are waitingAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.side_transport_pacing_smear_interval
duration1msthe smear interval for the task pacer that controls the amount of time each paced batch is going to take when broadcasting sidetransport updatesAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.closed_timestamp.target_duration
duration3sif nonzero, attempt to provide closed timestamp notifications for timestamps trailing cluster time by approximately this durationAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.dist_sender.circuit_breaker.cancellation.enabled
booleantruewhen enabled, in-flight requests will be cancelled when the circuit breaker tripsBasic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breaker.cancellation.write_grace_period
duration10show long after the circuit breaker trips to cancel write requests (these can't retry internally, so should be long enough to allow quorum/lease recovery)Basic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breaker.probe.interval
duration3sinterval between replica probesBasic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breaker.probe.threshold
duration3sduration of errors or stalls after which a replica will be probedBasic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breaker.probe.timeout
duration3stimeout for replica probesBasic/Standard/Advanced/Self-Hosted
kv.dist_sender.circuit_breakers.mode
enumerationliveness range onlyset of ranges to trip circuit breakers for failing or stalled replicas [no ranges = 0, liveness range only = 1, all ranges = 2]Basic/Standard/Advanced/Self-Hosted
kv.lease_transfer_read_summary.global_budget
byte size0 Bcontrols the maximum number of bytes that will be used to summarize the global segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Advanced/Self-Hosted
kv.lease_transfer_read_summary.local_budget
byte size4.0 MiBcontrols the maximum number of bytes that will be used to summarize the local segment of the timestamp cache during lease transfers and range merges. A smaller budget will result in loss of precision.Advanced/Self-Hosted
kv.log_range_and_node_events.enabled
booleantrueset to true to transactionally log range events (e.g., split, merge, add/remove voter/non-voter) into system.rangelogand node join and restart events into system.eventologAdvanced/Self-Hosted
kv.protectedts.reconciliation.interval
duration5m0sthe frequency for reconciling jobs with protected timestamp recordsAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.raft.leader_fortification.fraction_enabled
float1controls the fraction of ranges for which the raft leader fortification protocol is enabled. Leader fortification is needed for a range to use a Leader lease. Set to 0.0 to disable leader fortification and, by extension, Leader leases. Set to 1.0 to enable leader fortification for all ranges and, by extension, use Leader leases for all ranges which do not require expiration-based leases. Set to a value between 0.0 and 1.0 to gradually roll out Leader leases across the ranges in a cluster.Advanced/Self-Hosted
kv.range.range_size_hard_cap
byte size8.0 GiBhard cap on the maximum size a range is allowed to grow to withoutsplitting before writes to the range are blocked. Takes precedence over all other configurationsAdvanced/Self-Hosted
kv.range_split.by_load.enabled
(alias: kv.range_split.by_load_enabled)
booleantrueallow automatic splits of ranges based on where load is concentratedAdvanced/Self-Hosted
kv.range_split.load_cpu_threshold
duration500msthe CPU use per second over which, the range becomes a candidate for load based splittingAdvanced/Self-Hosted
kv.range_split.load_qps_threshold
integer2500the QPS over which, the range becomes a candidate for load based splittingAdvanced/Self-Hosted
kv.rangefeed.client.stream_startup_rate
integer100controls the rate per second the client will initiate new rangefeed stream for a single range; 0 implies unlimitedBasic/Standard/Advanced/Self-Hosted
kv.rangefeed.closed_timestamp_refresh_interval
duration3sthe interval at which closed-timestamp updatesare delivered to rangefeeds; set to 0 to use kv.closed_timestamp.side_transport_intervalAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.rangefeed.enabled
booleanfalseif set, rangefeed registration is enabledAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
kv.replica_circuit_breaker.slow_replication_threshold
duration1m0sduration after which slow proposals trip the per-Replica circuit breaker (zero duration disables breakers)Advanced/Self-Hosted
kv.replica_raft.leaderless_unavailable_threshold
duration1m0sduration after which leaderless replicas is considered unavailable. Set to 0 to disable leaderless replica availability checksAdvanced/Self-Hosted
kv.replica_stats.addsst_request_size_factor
integer50000the divisor that is applied to addsstable request sizes, then recorded in a leaseholders QPS; 0 means all requests are treated as cost 1Advanced/Self-Hosted
kv.replication_reports.interval
duration1m0sthe frequency for generating the replication_constraint_stats, replication_stats_report and replication_critical_localities reports (set to 0 to disable)Advanced/Self-Hosted
kv.snapshot_rebalance.max_rate
byte size32 MiBthe rate limit (bytes/sec) to use for rebalance and upreplication snapshotsAdvanced/Self-Hosted
kv.transaction.max_intents_and_locks
integer0maximum count of inserts or durable locks for a single transactions, 0 to disableBasic/Standard/Advanced/Self-Hosted
kv.transaction.max_intents_bytes
integer4194304maximum number of bytes used to track locks in transactionsBasic/Standard/Advanced/Self-Hosted
kv.transaction.max_refresh_spans_bytes
integer4194304maximum number of bytes used to track refresh spans in serializable transactionsBasic/Standard/Advanced/Self-Hosted
kv.transaction.randomized_anchor_key.enabled
booleanfalsedictates whether a transactions anchor key is randomized or notBasic/Standard/Advanced/Self-Hosted
kv.transaction.reject_over_max_intents_budget.enabled
booleanfalseif set, transactions that exceed their lock tracking budget (kv.transaction.max_intents_bytes) are rejected instead of having their lock spans imprecisely compressedBasic/Standard/Advanced/Self-Hosted
kv.transaction.write_buffering.enabled
booleantrueif enabled, transactional writes are buffered on the clientBasic/Standard/Advanced/Self-Hosted
kv.transaction.write_buffering.max_buffer_size
byte size4.0 MiBif non-zero, defines that maximum size of the buffer that will be used to buffer transactional writes per-transactionBasic/Standard/Advanced/Self-Hosted
kv.transaction.write_pipelining.locking_reads.enabled
booleantrueif enabled, transactional locking reads are pipelined through Raft consensusBasic/Standard/Advanced/Self-Hosted
kv.transaction.write_pipelining.ranged_writes.enabled
booleantrueif enabled, transactional ranged writes are pipelined through Raft consensusBasic/Standard/Advanced/Self-Hosted
kv.transaction.write_pipelining.enabled
(alias: kv.transaction.write_pipelining_enabled)
booleantrueif enabled, transactional writes are pipelined through Raft consensusBasic/Standard/Advanced/Self-Hosted
kv.transaction.write_pipelining.max_batch_size
(alias: kv.transaction.write_pipelining_max_batch_size)
integer128if non-zero, defines that maximum size batch that will be pipelined through Raft consensusBasic/Standard/Advanced/Self-Hosted
kvadmission.store.provisioned_bandwidth
byte size0 Bif set to a non-zero value, this is used as the provisioned bandwidth (in bytes/s), for each store. It can be overridden on a per-store basis using the --store flag. Note that setting the provisioned bandwidth to a positive value may enable disk bandwidth based admission control, since admission.disk_bandwidth_tokens.elastic.enabled defaults to trueAdvanced/Self-Hosted
kvadmission.store.snapshot_ingest_bandwidth_control.enabled
booleantrueif set to true, snapshot ingests will be subject to disk write control in ACAdvanced/Self-Hosted
kvadmission.store.snapshot_ingest_bandwidth_control.min_rate.enabled
booleantrueif set to true, snapshot ingests will be admitted at a minimum rate when kvadmission.store.provisioned_bandwidth is set to a non-zero value. Disabling this setting can lead to snapshots being starved out by foreground traffic.Advanced/Self-Hosted
log.channel_compatibility_mode.enabled
booleanfalsewhen true, logs will to log to their legacy (pre 26.1) logging channels; when false, logs will be logged to new logging channelsBasic/Standard/Advanced/Self-Hosted
obs.ash.buffer_size
integer1000000number of ASH samples to retain in memoryAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
obs.ash.enabled
booleanfalseenable active session history samplingAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
obs.ash.log_interval
duration10m0sinterval between periodic ASH top-N workload summary logs; also used as the lookback window for ASH reports written by the env sampler profilerAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
obs.ash.log_top_n
integer10maximum number of entries in periodic ASH workload summary, ranked by sample count descendingAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
obs.ash.response_limit
integer10000maximum number of ASH samples returned per node in fan-out responsesBasic/Standard/Advanced/Self-Hosted
obs.ash.sample_interval
duration1sinterval between ASH samplesAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
obs.tablemetadata.automatic_updates.enabled
booleanfalseenables automatic updates of the table metadata cache system.table_metadataBasic/Standard/Advanced/Self-Hosted
obs.tablemetadata.data_valid_duration
duration20m0sthe duration for which the data in system.table_metadata is considered validBasic/Standard/Advanced/Self-Hosted
schedules.backup.gc_protection.enabled
booleantrueenable chaining of GC protection across backups run as part of a scheduleBasic/Standard/Advanced/Self-Hosted
security.client_cert.san_required.enabled
booleanfalsemandates a requirement for client certs to contain SANAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
security.client_cert.subject_required.enabled
booleanfalsemandates a requirement for subject role to be set for db userAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
security.ocsp.mode
enumerationoffuse OCSP to check whether TLS certificates are revoked. If the OCSP server is unreachable, in strict mode all certificates will be rejected and in lax mode all certificates will be accepted. [off = 0, lax = 1, strict = 2]Basic/Standard/Advanced/Self-Hosted
security.ocsp.timeout
duration3stimeout before considering the OCSP server unreachableBasic/Standard/Advanced/Self-Hosted
security.provisioning.ldap.enabled
booleanfalseenables automatic creation of SQL users upon successful LDAP loginBasic/Standard/Advanced/Self-Hosted
server.auth_log.sql_connections.enabled
booleanfalseif set, log SQL client connect and disconnect events to the SESSIONS log channel (note: may hinder performance on loaded nodes)Basic/Standard/Advanced/Self-Hosted
server.auth_log.sql_sessions.enabled
booleanfalseif set, log verbose SQL session authentication events to the SESSIONS log channel (note: may hinder performance on loaded nodes). Session start and end events are always logged regardless of this setting; disable the SESSIONS log channel to suppress them.Basic/Standard/Advanced/Self-Hosted
server.authentication_cache.enabled
booleantrueenables a cache used during authentication to avoid lookups to system tables when retrieving per-user authentication-related informationBasic/Standard/Advanced/Self-Hosted
server.child_metrics.enabled
booleanfalseenables the exporting of child metrics, additional prometheus time series with extra labelsBasic/Standard/Advanced/Self-Hosted
server.child_metrics.include_aggregate.enabled
booleantrueinclude the reporting of the aggregate time series when child metrics are enabled. This cluster setting has no effect if child metrics are disabled.Basic/Standard/Advanced/Self-Hosted
server.clock.forward_jump_check.enabled
(alias: server.clock.forward_jump_check_enabled)
booleanfalseif enabled, forward clock jumps > max_offset/2 will cause a panicBasic/Standard/Advanced/Self-Hosted
server.clock.persist_upper_bound_interval
duration0sthe interval between persisting the wall time upper bound of the clock. The clock does not generate a wall time greater than the persisted timestamp and will panic if it sees a wall time greater than this value. When cockroach starts, it waits for the wall time to catch-up till this persisted timestamp. This guarantees monotonic wall time across server restarts. Not setting this or setting a value of 0 disables this feature.Basic/Standard/Advanced/Self-Hosted
server.consistency_check.max_rate
byte size8.0 MiBthe rate limit (bytes/sec) to use for consistency checks; used in conjunction with server.consistency_check.interval to control the frequency of consistency checks. Note that setting this too high can negatively impact performance.Advanced/Self-Hosted
server.eventlog.enabled
booleantrueif set, logged notable events are also stored in the table system.eventlogBasic/Standard/Advanced/Self-Hosted
server.eventlog.ttl
duration2160h0m0sif nonzero, entries in system.eventlog older than this duration are periodically purgedBasic/Standard/Advanced/Self-Hosted
server.host_based_authentication.configuration
stringhost-based authentication configuration to use during connection authenticationBasic/Standard/Advanced/Self-Hosted
server.hot_ranges_request.node.timeout
duration5m0sthe duration allowed for a single node to return hot range data before the request is cancelled; if set to 0, there is no timeoutBasic/Standard/Advanced/Self-Hosted
server.hsts.enabled
booleanfalseif true, HSTS headers will be sent along with all HTTP requests. The headers will contain a max-age setting of one year. Browsers honoring the header will always use HTTPS to access the DB Console. Ensure that TLS is correctly configured prior to enabling.Basic/Standard/Advanced/Self-Hosted
server.http.base_path
string/path to redirect the user to upon succcessful loginBasic/Standard/Advanced/Self-Hosted
server.identity_map.configuration
stringsystem-identity to database-username mappingsBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.audience
stringsets accepted audience values for JWT logins over the SQL interfaceBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.claim
stringsets the JWT claim that is parsed to get the usernameBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.client.timeout
duration15ssets the client timeout for external calls made during JWT authentication (e.g. fetching JWKS, etc.)Basic/Standard/Advanced/Self-Hosted
server.jwt_authentication.enabled
booleanfalseenables or disables JWT login for the SQL interfaceBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.issuers.configuration
(alias: server.jwt_authentication.issuers)
stringsets accepted issuer values for JWT logins over the SQL interface which can be a single issuer URL string or a JSON string containing an array of issuer URLs or a JSON object containing map of issuer URLS to JWKS URIsBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.issuers.custom_ca
stringsets the PEM encoded custom root CA for verifying certificates while fetching JWKSBasic/Standard/Advanced/Self-Hosted
server.jwt_authentication.jwks
string{"keys":[]}sets the public key set for JWT logins over the SQL interface (JWKS format)Basic/Standard/Advanced/Self-Hosted
server.jwt_authentication.jwks_auto_fetch.enabled
booleanfalseenables or disables automatic fetching of JWKS from the issuer's well-known endpoint or JWKS URI set in JWTAuthIssuersConfig. If this is enabled, the server.jwt_authentication.jwks will be ignored.Basic/Standard/Advanced/Self-Hosted
server.ldap_authentication.client.tls_certificate
stringsets the client certificate PEM for establishing mTLS connection with LDAP serverBasic/Standard/Advanced/Self-Hosted
server.ldap_authentication.client.tls_key
stringsets the client key PEM for establishing mTLS connection with LDAP serverBasic/Standard/Advanced/Self-Hosted
server.ldap_authentication.domain.custom_ca
stringsets the PEM encoded custom root CA for verifying domain certificates when establishing connection with LDAP serverBasic/Standard/Advanced/Self-Hosted
server.log_gc.max_deletions_per_cycle
integer1000the maximum number of entries to delete on each purge of log-like system tablesBasic/Standard/Advanced/Self-Hosted
server.log_gc.period
duration1h0m0sthe period at which log-like system tables are checked for old entriesBasic/Standard/Advanced/Self-Hosted
server.max_connections_per_gateway
integer-1the maximum number of SQL connections per gateway allowed at a given time (note: this will only limit future connection attempts and will not affect already established connections). Negative values result in unlimited number of connections. Superusers are not affected by this limit.Basic/Standard/Advanced/Self-Hosted
server.max_open_transactions_per_gateway
integer-1the maximum number of open SQL transactions per gateway allowed at a given time. Negative values result in unlimited number of connections. Superusers are not affected by this limit.Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.autologin.enabled
(alias: server.oidc_authentication.autologin)
booleanfalseif true, logged-out visitors to the DB Console will be automatically redirected to the OIDC login endpointBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.button_text
stringLog in with your OIDC providertext to show on button on DB Console login page to login with your OIDC provider (only shown if OIDC is enabled)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.claim_json_key
stringsets JSON key of principal to extract from payload after OIDC authentication completes (usually email or sid)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.client.timeout
duration15ssets the client timeout for external calls made during OIDC authentication (e.g. authorization code flow, etc.)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.client_id
stringsets OIDC client idBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.client_secret
stringsets OIDC client secretBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.enabled
booleanfalseenables or disabled OIDC login for the DB ConsoleBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.principal_regex
string(.+)regular expression to apply to extracted principal (see claim_json_key setting) to translate to SQL user (golang regex format, must include 1 grouping to extract)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.provider.custom_ca
stringsets the PEM encoded custom root CA for verifying certificates while authenticating through the OIDC providerBasic/Standard/Advanced/Self-Hosted
server.oidc_authentication.provider_url
stringsets OIDC provider URL ({provider_url}/.well-known/openid-configuration must resolve)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.redirect_url
stringhttps://localhost:8080/oidc/v1/callbacksets OIDC redirect URL via a URL string or a JSON string containing a required `redirect_urls` key with an object that maps from region keys to URL strings (URLs should point to your load balancer and must route to the path /oidc/v1/callback)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.scopes
stringopenidsets OIDC scopes to include with authentication request (space delimited list of strings, required to start with `openid`)Basic/Standard/Advanced/Self-Hosted
server.oidc_authentication.tls_insecure_skip_verify.enabled
booleanfalseif true, TLS certificate verification is skipped for connections to the OIDC provider (insecure)Basic/Standard/Advanced/Self-Hosted
server.rangelog.ttl
duration720h0m0sif nonzero, entries in system.rangelog older than this duration are periodically purgedAdvanced/Self-Hosted
server.redact_sensitive_settings.enabled
booleanfalseenables or disables the redaction of sensitive settings in the output of SHOW CLUSTER SETTINGS and SHOW ALL CLUSTER SETTINGS for users without the MODIFYCLUSTERSETTING privilegeBasic/Standard/Advanced/Self-Hosted
server.shutdown.connections.timeout
(alias: server.shutdown.connection_wait)
duration0sthe maximum amount of time a server waits for all SQL connections to be closed before proceeding with a drain. (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Basic/Standard/Advanced/Self-Hosted
server.shutdown.initial_wait
(alias: server.shutdown.drain_wait)
duration0sthe amount of time a server waits in an unready state before proceeding with a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting. --drain-wait is to specify the duration of the whole draining process, while server.shutdown.initial_wait is to set the wait time for health probes to notice that the node is not ready.)Basic/Standard/Advanced/Self-Hosted
server.shutdown.lease_transfer_iteration.timeout
(alias: server.shutdown.lease_transfer_wait)
duration5sthe timeout for a single iteration of the range lease transfer phase of draining (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Advanced/Self-Hosted
server.shutdown.transactions.timeout
(alias: server.shutdown.query_wait)
duration10sthe timeout for waiting for active transactions to finish during a drain (note that the --drain-wait parameter for cockroach node drain may need adjustment after changing this setting)Basic/Standard/Advanced/Self-Hosted
server.sql_tcp_keep_alive.count
integer3maximum number of probes that will be sent out before a connection is dropped because it's unresponsive (Linux and Darwin only). The value 0 is the operating system default.Basic/Standard/Advanced/Self-Hosted
server.sql_tcp_keep_alive.idle
duration0stime with no network activity before sending a TCP keepalive probe (Linux and Darwin only). If 0, the value of server.sql_tcp_keep_alive.interval is used. The value 0 is the operating system default.Basic/Standard/Advanced/Self-Hosted
server.sql_tcp_keep_alive.interval
duration10stime between keep alive probes and idle time before probes are sent out. The value 0 is the operating system default.Basic/Standard/Advanced/Self-Hosted
server.sql_tcp_user.timeout
duration0sspecifies the maximum amount of time that transmitted data can remain unacknowledged before the underlying TCP connection is forcefully closed. (Linux and Darwin only). The value 0 is the operating system default.Basic/Standard/Advanced/Self-Hosted
server.time_until_store_dead
duration5m0sthe time after which if there is no new gossiped information about a store, it is considered deadBasic/Standard/Advanced/Self-Hosted
server.user_login.cert_password_method.auto_scram_promotion.enabled
booleantruewhether to automatically promote cert-password authentication to use SCRAMBasic/Standard/Advanced/Self-Hosted
server.user_login.downgrade_scram_stored_passwords_to_bcrypt.enabled
booleantrueif server.user_login.password_encryption=crdb-bcrypt, this controls whether to automatically re-encode stored passwords using scram-sha-256 to crdb-bcryptBasic/Standard/Advanced/Self-Hosted
server.user_login.min_password_length
integer1the minimum length accepted for passwords set in cleartext via SQL. Note that a value lower than 1 is ignored: passwords cannot be empty in any case. This setting only applies when adding new users or altering an existing user's password; it will not affect existing logins.Basic/Standard/Advanced/Self-Hosted
server.user_login.password_encryption
enumerationscram-sha-256which hash method to use to encode cleartext passwords passed via ALTER/CREATE USER/ROLE WITH PASSWORD [crdb-bcrypt = 2, scram-sha-256 = 3]Basic/Standard/Advanced/Self-Hosted
server.user_login.password_hashes.default_cost.crdb_bcrypt
integer10the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method crdb-bcrypt (allowed range: 4-31)Basic/Standard/Advanced/Self-Hosted
server.user_login.password_hashes.default_cost.scram_sha_256
integer10610the hashing cost to use when storing passwords supplied as cleartext by SQL clients with the hashing method scram-sha-256 (allowed range: 4096-240000000000)Basic/Standard/Advanced/Self-Hosted
server.user_login.rehash_scram_stored_passwords_on_cost_change.enabled
booleantrueif server.user_login.password_hashes.default_cost.scram_sha_256 differs from, the cost in a stored hash, this controls whether to automatically re-encode stored passwords using scram-sha-256 with the new default costBasic/Standard/Advanced/Self-Hosted
server.user_login.timeout
duration10stimeout after which client authentication times out if some system range is unavailable (0 = no timeout)Basic/Standard/Advanced/Self-Hosted
server.user_login.upgrade_bcrypt_stored_passwords_to_scram.enabled
booleantrueif server.user_login.password_encryption=scram-sha-256, this controls whether to automatically re-encode stored passwords using crdb-bcrypt to scram-sha-256Basic/Standard/Advanced/Self-Hosted
server.web_session.purge.ttl
duration1h0m0sif nonzero, entries in system.web_sessions older than this duration are periodically purgedBasic/Standard/Advanced/Self-Hosted
server.web_session.timeout
(alias: server.web_session_timeout)
duration168h0m0sthe duration that a newly created web session will be validBasic/Standard/Advanced/Self-Hosted
spanconfig.bounds.enabled
booleantruedictates whether span config bounds are consulted when serving span configs for secondary tenantsAdvanced/Self-Hosted
spanconfig.range_coalescing.system.enabled
(alias: spanconfig.storage_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs, for the ranges specific to the system tenantAdvanced/Self-Hosted
spanconfig.range_coalescing.application.enabled
(alias: spanconfig.tenant_coalesce_adjacent.enabled)
booleantruecollapse adjacent ranges with the same span configs across all secondary tenant keyspacesAdvanced/Self-Hosted
sql.auth.change_own_password.enabled
booleanfalsecontrols whether a user is allowed to change their own password, even if they have no other privilegesBasic/Standard/Advanced/Self-Hosted
sql.auth.grant_option_for_owner.enabled
booleantruedetermines whether the GRANT OPTION for privileges is implicitly given to the owner of an objectBasic/Standard/Advanced/Self-Hosted
sql.auth.grant_option_inheritance.enabled
booleantruedetermines whether the GRANT OPTION for privileges is inherited through role membershipBasic/Standard/Advanced/Self-Hosted
sql.auth.public_schema_create_privilege.enabled
booleantruedetermines whether to grant all users the CREATE privileges on the public schema when it is createdBasic/Standard/Advanced/Self-Hosted
sql.auth.skip_underlying_view_privilege_checks.enabled
booleanfalsedetermines whether to skip privilege checks on tables underlying views. When enabled, users with SELECT privileges on a view can query it regardless of their privileges on the underlying tables, and row-level security policies are evaluated as the invoking user rather than the view owner. This restores pre-v26.2 behavior.Basic/Standard/Advanced/Self-Hosted
sql.catalog.allow_leased_descriptors.enabled
booleantrueif true, catalog views (crdb_internal, information_schema, pg_catalog) can use leased descriptors for improved performanceBasic/Standard/Advanced/Self-Hosted
sql.closed_session_cache.capacity
integer1000the maximum number of sessions in the cacheBasic/Standard/Advanced/Self-Hosted
sql.closed_session_cache.time_to_live
integer3600the maximum time to live, in secondsBasic/Standard/Advanced/Self-Hosted
sql.contention.event_store.capacity
byte size64 MiBthe in-memory storage capacity per-node of contention event storeBasic/Standard/Advanced/Self-Hosted
sql.contention.event_store.duration_threshold
duration0sminimum contention duration to cause the contention events to be collected into crdb_internal.transaction_contention_eventsBasic/Standard/Advanced/Self-Hosted
sql.contention.record_serialization_conflicts.enabled
booleantrueenables recording 40001 errors with conflicting txn meta as SERIALIZATION_CONFLICTcontention events into crdb_internal.transaction_contention_eventsBasic/Standard/Advanced/Self-Hosted
sql.contention.txn_id_cache.max_size
byte size64 MiBthe maximum byte size TxnID cache will use (set to 0 to disable)Basic/Standard/Advanced/Self-Hosted
sql.cross_db_fks.enabled
booleanfalseif true, creating foreign key references across databases is allowedBasic/Standard/Advanced/Self-Hosted
sql.cross_db_sequence_owners.enabled
booleanfalseif true, creating sequences owned by tables from other databases is allowedBasic/Standard/Advanced/Self-Hosted
sql.cross_db_sequence_references.enabled
booleanfalseif true, sequences referenced by tables from other databases are allowedBasic/Standard/Advanced/Self-Hosted
sql.cross_db_views.enabled
booleanfalseif true, creating views that refer to other databases is allowedBasic/Standard/Advanced/Self-Hosted
sql.defaults.cost_scans_with_default_col_size.enabled
booleanfalsesetting to true uses the same size for all columns to compute scan cost
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.datestyle
enumerationiso, mdydefault value for DateStyle session setting [iso, mdy = 0, iso, dmy = 1, iso, ymd = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.default_hash_sharded_index_bucket_count
integer16used as bucket count if bucket count is not specified in hash sharded index definition
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.default_int_size
integer8the size, in bytes, of an INT type
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.disallow_full_table_scans.enabled
booleanfalsesetting to true rejects queries that have planned a full table scan; set large_full_scan_rows > 0 to allow small full table scans estimated to read fewer than large_full_scan_rows
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.distsql
enumerationautodefault distributed SQL execution mode [off = 0, auto = 1, on = 2, always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_alter_column_type.enabled
booleanfalsedefault value for experimental_alter_column_type session setting; enables the use of ALTER COLUMN TYPE for general conversions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_distsql_planning
enumerationoffdefault experimental_distsql_planning mode; enables experimental opt-driven DistSQL planning [off = 0, on = 1]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_enable_unique_without_index_constraints.enabled
booleanfalsedefault value for experimental_enable_unique_without_index_constraints session setting;disables unique without index constraints by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_implicit_column_partitioning.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for the use of implicit column partitioning
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.experimental_temporary_tables.enabled
booleanfalsedefault value for experimental_enable_temp_tables; allows for use of temporary tables by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.foreign_key_cascades_limit
integer10000default value for foreign_key_cascades_limit session setting; limits the number of cascading operations that run as part of a single query
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.idle_in_session_timeout
duration0sdefault value for the idle_in_session_timeout; default value for the idle_in_session_timeout session setting; controls the duration a session is permitted to idle before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.idle_in_transaction_session_timeout
duration0sdefault value for the idle_in_transaction_session_timeout; controls the duration a session is permitted to idle in a transaction before the session is terminated; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.implicit_select_for_update.enabled
booleantruedefault value for enable_implicit_select_for_update session setting; enables FOR UPDATE locking during the row-fetch phase of mutation statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.insert_fast_path.enabled
booleantruedefault value for enable_insert_fast_path session setting; enables a specialized insert path
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.intervalstyle
enumerationpostgresdefault value for IntervalStyle session setting [postgres = 0, iso_8601 = 1, sql_standard = 2]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.large_full_scan_rows
float0default value for large_full_scan_rows session variable which determines the table size at which full scans are considered large and disallowed when disallow_full_table_scans is set to true; set to 0 to reject all full table or full index scans when disallow_full_table_scans is true
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.locality_optimized_partitioned_index_scan.enabled
booleantruedefault value for locality_optimized_partitioned_index_scan session setting; enables searching for rows in the current region before searching remote regions
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.lock_timeout
duration0sdefault value for the lock_timeout; default value for the lock_timeout session setting; controls the duration a query is permitted to wait while attempting to acquire a lock on a key or while blocking on an existing lock in order to perform a non-locking read on a key; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.on_update_rehome_row.enabled
booleantruedefault value for on_update_rehome_row; enables ON UPDATE rehome_row() expressions to trigger on updates
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.optimizer_use_histograms.enabled
booleantruedefault value for optimizer_use_histograms session setting; enables usage of histograms in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.optimizer_use_multicol_stats.enabled
booleantruedefault value for optimizer_use_multicol_stats session setting; enables usage of multi-column stats in the optimizer by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.override_alter_primary_region_in_super_region.enabled
booleanfalsedefault value for override_alter_primary_region_in_super_region; allows for altering the primary region even if the primary region is a member of a super region
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.override_multi_region_zone_config.enabled
booleanfalsedefault value for override_multi_region_zone_config; allows for overriding the zone configs of a multi-region table or database
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.prefer_lookup_joins_for_fks.enabled
booleanfalsedefault value for prefer_lookup_joins_for_fks session setting; causes foreign key operations to use lookup joins when possible
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.primary_region
stringif not empty, all databases created without a PRIMARY REGION will implicitly have the given PRIMARY REGION
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.reorder_joins_limit
integer8default number of joins to reorder
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.require_explicit_primary_keys.enabled
booleanfalsedefault value for requiring explicit primary keys in CREATE TABLE statements
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.results_buffer.size
byte size512 KiBdefault size of the buffer that accumulates results for a statement or a batch of statements before they are sent to the client. This can be overridden on an individual connection with the 'results_buffer_size' parameter. Note that auto-retries generally only happen while no results have been delivered to the client, so reducing this size can increase the number of retriable errors a client receives. On the other hand, increasing the buffer size can increase the delay until the client receives the first result row. Updating the setting only affects new connections. Setting to 0 disables any buffering.
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.serial_normalization
enumerationrowiddefault handling of SERIAL in table definitions [rowid = 0, virtual_sequence = 1, sql_sequence = 2, sql_sequence_cached = 3, unordered_rowid = 4, sql_sequence_cached_node = 5]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.statement_timeout
duration0sdefault value for the statement_timeout; default value for the statement_timeout session setting; controls the duration a query is permitted to run before it is canceled; if set to 0, there is no timeout
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.stub_catalog_tables.enabled
booleantruedefault value for stub_catalog_tables session setting
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.transaction_rows_read_err
integer0the limit for the number of rows read by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.transaction_rows_read_log
integer0the threshold for the number of rows read by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.transaction_rows_written_err
integer0the limit for the number of rows written by a SQL transaction which - once exceeded - will fail the transaction (or will trigger a logging event to SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.transaction_rows_written_log
integer0the threshold for the number of rows written by a SQL transaction which - once exceeded - will trigger a logging event to SQL_PERF (or SQL_INTERNAL_PERF for internal transactions); use 0 to disable
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.use_declarative_schema_changer
enumerationondefault value for use_declarative_schema_changer session setting;disables new schema changer by default [off = 0, on = 1, unsafe = 2, unsafe_always = 3]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.vectorize
enumerationondefault vectorize mode [on = 0, on = 1, on = 2, experimental_always = 3, off = 4]
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.defaults.zigzag_join.enabled
booleanfalsedefault value for enable_zigzag_join session setting; disallows use of zig-zag join by default
This cluster setting is being kept to preserve backwards-compatibility.
This session variable default should now be configured using ALTER ROLE... SET		Basic/Standard/Advanced/Self-Hosted
sql.distsql.temp_storage.workmem
byte size64 MiBmaximum amount of memory in bytes a processor can use before falling back to temp storageBasic/Standard/Advanced/Self-Hosted
sql.guardrails.max_row_size_err
byte size80 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an error is returned; use 0 to disableBasic/Standard/Advanced/Self-Hosted
sql.guardrails.max_row_size_log
byte size16 MiBmaximum size of row (or column family if multiple column families are in use) that SQL can write to the database, above which an event is logged to SQL_PERF (or SQL_INTERNAL_PERF if the mutating statement was internal); use 0 to disableBasic/Standard/Advanced/Self-Hosted
sql.hash_sharded_range_pre_split.max
integer16max pre-split ranges to have when adding hash sharded index to an existing tableBasic/Standard/Advanced/Self-Hosted
sql.index_recommendation.drop_unused_duration
duration168h0m0sthe index unused duration at which we begin to recommend dropping the indexBasic/Standard/Advanced/Self-Hosted
sql.insights.anomaly_detection.enabled
booleantrueenable per-fingerprint latency recording and anomaly detectionBasic/Standard/Advanced/Self-Hosted
sql.insights.anomaly_detection.latency_threshold
duration50msstatements must surpass this threshold to trigger anomaly detection and identificationBasic/Standard/Advanced/Self-Hosted
sql.insights.anomaly_detection.memory_limit
byte size1.0 MiBthe maximum amount of memory allowed for tracking statement latenciesBasic/Standard/Advanced/Self-Hosted
sql.insights.execution_insights_capacity
integer1000the size of the per-node store of execution insightsBasic/Standard/Advanced/Self-Hosted
sql.insights.high_retry_count.threshold
integer10the number of retries a slow statement must have undergone for its high retry count to be highlighted as a potential problemBasic/Standard/Advanced/Self-Hosted
sql.insights.latency_threshold
duration100msamount of time after which an executing statement is considered slow. Use 0 to disable.Basic/Standard/Advanced/Self-Hosted
sql.log.redact_names.enabled
booleanfalseif set, schema object identifers are redacted in SQL statements that appear in event logsBasic/Standard/Advanced/Self-Hosted
sql.log.scan_row_count_misestimate.enabled
booleanfalsewhen set to true, log a warning when a scan's actual row count differs significantly from the optimizer's estimateBasic/Standard/Advanced/Self-Hosted
sql.log.slow_query.experimental_full_table_scans.enabled
booleanfalsewhen set to true, statements that perform a full table/index scan will be logged to the slow query log even if they do not meet the latency threshold. Must have the slow query log enabled for this setting to have any effect.Basic/Standard/Advanced/Self-Hosted
sql.log.slow_query.internal_queries.enabled
booleanfalsewhen set to true, internal queries which exceed the slow query log threshold are logged to a separate log. Must have the slow query log enabled for this setting to have any effect.Basic/Standard/Advanced/Self-Hosted
sql.log.slow_query.latency_threshold
duration0swhen set to non-zero, log statements whose service latency exceeds the threshold to a secondary logger on each nodeBasic/Standard/Advanced/Self-Hosted
sql.log.user_audit
stringuser/role-based audit logging configurationBasic/Standard/Advanced/Self-Hosted
sql.log.user_audit.reduced_config.enabled
booleanfalseenables logic to compute a reduced audit configuration, computing the audit configuration only once at session start instead of at each SQL event. The tradeoff with the increase in performance (~5%), is that changes to the audit configuration (user role memberships/cluster setting) are not reflected within session. Users will need to start a new session to see these changes in their auditing behaviour.Basic/Standard/Advanced/Self-Hosted
sql.metrics.application_name.enabled
booleanfalsewhen enabled, SQL metrics would export application name as and additional label as part of child metrics. The number of unique label combinations is limited to 5000 by default.Basic/Standard/Advanced/Self-Hosted
sql.metrics.database_name.enabled
booleanfalsewhen enabled, SQL metrics would export database name as and additional label as part of child metrics. The number of unique label combinations is limited to 5000 by default.Basic/Standard/Advanced/Self-Hosted
sql.metrics.index_usage_stats.enabled
booleantruecollect per index usage statisticsBasic/Standard/Advanced/Self-Hosted
sql.metrics.max_mem_reported_stmt_fingerprints
integer100000the maximum number of reported statement fingerprints stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.max_mem_reported_txn_fingerprints
integer100000the maximum number of reported transaction fingerprints stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.max_mem_stmt_fingerprints
integer7500the maximum number of statement fingerprints stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.max_mem_txn_fingerprints
integer7500the maximum number of transaction fingerprints stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.dump_to_logs.enabled
(alias: sql.metrics.statement_details.dump_to_logs)
booleanfalsedump collected statement statistics to node logs when periodically clearedBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.enabled
booleantruecollect per-statement query statisticsBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.gateway_node.enabled
booleanfalsesave the gateway node for each statement fingerprint. If false, the value will be stored as 0.Basic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.index_recommendation_collection.enabled
booleantruegenerate an index recommendation for each fingerprint IDBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.max_mem_reported_idx_recommendations
integer5000the maximum number of reported index recommendation info stored in memoryBasic/Standard/Advanced/Self-Hosted
sql.metrics.statement_details.threshold
duration0sminimum execution time to cause statement statistics to be collected. If configured, no transaction stats are collected.Basic/Standard/Advanced/Self-Hosted
sql.metrics.transaction_details.enabled
booleantruecollect per-application transaction statisticsBasic/Standard/Advanced/Self-Hosted
sql.multiple_modifications_of_table.enabled
booleanfalseif true, allow statements containing multiple INSERT ON CONFLICT, UPSERT, UPDATE, or DELETE subqueries modifying the same table, at the risk of data corruption if the same row is modified multiple times by a single statement (multiple INSERT subqueries without ON CONFLICT cannot cause corruption and are always allowed)Basic/Standard/Advanced/Self-Hosted
sql.multiregion.drop_primary_region.enabled
booleantrueallows dropping the PRIMARY REGION of a database if it is the last regionBasic/Standard/Advanced/Self-Hosted
sql.notices.enabled
booleantrueenable notices in the server/client protocol being sentBasic/Standard/Advanced/Self-Hosted
sql.optimizer.uniqueness_checks_for_gen_random_uuid.enabled
booleanfalseif enabled, uniqueness checks may be planned for mutations of UUID columns updated with gen_random_uuid(); otherwise, uniqueness is assumed due to near-zero collision probabilityBasic/Standard/Advanced/Self-Hosted
sql.schema.approx_max_object_count
integer20000approximate maximum number of schema objects allowed in the cluster; the check uses cached statistics, so the actual count may slightly exceed this limit; set to 0 to disableBasic/Standard/Advanced/Self-Hosted
sql.schema.auto_unlock.enabled
booleantruecontrols whether DDL operations will attempt to automatically unlock and re-lock schema_locked tables. When this setting is false, DDL on schema_locked tables is blocked unless the user manually unlocks the table first. The schema_locked storage parameter improves changefeed performance by locking the table's schema from the perspective of the changefeed.Basic/Standard/Advanced/Self-Hosted
sql.schema.telemetry.recurrence
string@weeklycron-tab recurrence for SQL schema telemetry jobAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
sql.spatial.experimental_box2d_comparison_operators.enabled
booleanfalseenables the use of certain experimental box2d comparison operatorsBasic/Standard/Advanced/Self-Hosted
sql.sqlcommenter.enabled
booleanfalseenables support for sqlcommenter. Key value parsed from sqlcommenter comments will be included in sql insights and sql logs. See https://google.github.io/sqlcommenter/ for more details.Basic/Standard/Advanced/Self-Hosted
sql.stats.activity.persisted_rows.max
integer200000maximum number of rows of statement and transaction activity that will be persisted in the system tablesBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_collection.enabled
booleantrueautomatic statistics collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_collection.fraction_stale_rows
float0.2target fraction of stale rows per table that will trigger a statistics refreshBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_collection.min_stale_rows
integer500target minimum number of stale rows per table that will trigger a statistics refreshBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_extremes_concurrency_limit
integer128determines the maximum number of concurrent automatic partial USING EXTREMES table statistics collection jobsBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_full_collection.enabled
booleantrueautomatic full statistics collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_full_concurrency_limit
integerSee description.determines the maximum number of concurrent automatic full table statistics collection jobs. The default value is computed as the number of vCPUs in a node divided by 2.Basic/Standard/Advanced/Self-Hosted
sql.stats.automatic_partial_collection.enabled
booleantrueautomatic partial statistics collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_partial_collection.fraction_stale_rows
float0.05target fraction of stale rows per table that will trigger a partial statistics refreshBasic/Standard/Advanced/Self-Hosted
sql.stats.automatic_partial_collection.min_stale_rows
integer100target minimum number of stale rows per table that will trigger a partial statistics refreshBasic/Standard/Advanced/Self-Hosted
sql.stats.canary_fraction
float0probability that table statistics will use canary mode instead of stable mode for query planning [0.0-1.0]Basic/Standard/Advanced/Self-Hosted
sql.stats.cleanup.recurrence
string@hourlycron-tab recurrence for SQL Stats cleanup jobBasic/Standard/Advanced/Self-Hosted
sql.stats.detailed_latency_metrics.enabled
booleanfalselabel latency metrics with the statement fingerprint. Workloads with tens of thousands of distinct query fingerprints should leave this setting false. (experimental, affects performance for workloads with high fingerprint cardinality)Basic/Standard/Advanced/Self-Hosted
sql.stats.error_on_concurrent_create_stats.enabled
booleanfalseset to true to error on concurrent CREATE STATISTICS jobs, instead of skipping themBasic/Standard/Advanced/Self-Hosted
sql.stats.flush.enabled
booleantrueif set, SQL execution statistics are periodically flushed to diskBasic/Standard/Advanced/Self-Hosted
sql.stats.flush.interval
duration10m0sthe interval at which SQL execution statistics are flushed to disk, this value must be less than or equal to 1 hourBasic/Standard/Advanced/Self-Hosted
sql.stats.forecasts.enabled
booleantruewhen true, enables generation of statistics forecasts by default for all tablesBasic/Standard/Advanced/Self-Hosted
sql.stats.forecasts.max_decrease
float0.3333333333333333the most a prediction is allowed to decrease, expressed as the minimum ratio of the prediction to the lowest prior observationBasic/Standard/Advanced/Self-Hosted
sql.stats.forecasts.min_goodness_of_fit
float0.95the minimum R² (goodness of fit) measurement required from all predictive models to use a forecastBasic/Standard/Advanced/Self-Hosted
sql.stats.forecasts.min_observations
integer3the mimimum number of observed statistics required to produce a statistics forecastBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_buckets.count
integer200maximum number of histogram buckets to build during table statistics collectionBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_buckets.include_most_common_values.enabled
booleantruewhether to include most common values as histogram bucketsBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_buckets.max_fraction_most_common_values
float0.1maximum fraction of histogram buckets to use for most common valuesBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_collection.enabled
booleantruehistogram collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.histogram_samples.count
integer0number of rows sampled for histogram construction during table statistics collection. Not setting this or setting a value of 0 means that a reasonable sample size will be automatically picked based on the table size.Basic/Standard/Advanced/Self-Hosted
sql.stats.multi_column_collection.enabled
booleantruemulti-column statistics collection modeBasic/Standard/Advanced/Self-Hosted
sql.stats.non_default_columns.min_retention_period
duration24h0m0sminimum retention period for table statistics collected on non-default columnsBasic/Standard/Advanced/Self-Hosted
sql.stats.non_indexed_json_histograms.enabled
booleanfalseset to true to collect table statistics histograms on non-indexed JSON columnsBasic/Standard/Advanced/Self-Hosted
sql.stats.persisted_rows.max
integer1000000maximum number of rows of statement and transaction statistics that will be persisted in the system tables before compaction beginsBasic/Standard/Advanced/Self-Hosted
sql.stats.post_events.enabled
booleanfalseif set, an event is logged for every successful CREATE STATISTICS jobBasic/Standard/Advanced/Self-Hosted
sql.stats.response.max
integer20000the maximum number of statements and transaction stats returned in a CombinedStatements requestBasic/Standard/Advanced/Self-Hosted
sql.stats.response.show_internal.enabled
booleanfalsecontrols if statistics for internal executions should be returned by the CombinedStatements and if internal sessions should be returned by the ListSessions endpoints. These endpoints are used to display statistics on the SQL Activity pagesBasic/Standard/Advanced/Self-Hosted
sql.stats.system_tables.enabled
booleantruewhen true, enables use of statistics on system tables by the query optimizerBasic/Standard/Advanced/Self-Hosted
sql.stats.system_tables_autostats.enabled
booleantruewhen true, enables automatic collection of statistics on system tablesBasic/Standard/Advanced/Self-Hosted
sql.stats.table_statistics_cache.capacity
integer256the maximum number of table statistics entries stored in the LRU cache. Each cache entry corresponds to a single table.Basic/Standard/Advanced/Self-Hosted
sql.stats.virtual_computed_columns.enabled
booleantrueset to true to collect table statistics on virtual computed columnsBasic/Standard/Advanced/Self-Hosted
sql.telemetry.query_sampling.enabled
booleanfalsewhen set to true, executed queries will emit an event on the telemetry logging channelBasic/Standard/Advanced/Self-Hosted
sql.telemetry.query_sampling.internal.enabled
booleanfalsewhen set to true, internal queries will be sampled in telemetry loggingBasic/Standard/Advanced/Self-Hosted
sql.telemetry.query_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample executions for telemetry, note that it is recommended that this value shares a log-line limit of 10 logs per second on the telemetry pipeline with all other telemetry events. If sampling mode is set to 'transaction', this value is ignored.Basic/Standard/Advanced/Self-Hosted
sql.telemetry.query_sampling.mode
enumerationstatementthe execution level used for telemetry sampling. If set to 'statement', events are sampled at the statement execution level. If set to 'transaction', events are sampled at the transaction execution level, i.e. all statements for a transaction will be logged and are counted together as one sampled event (events are still emitted one per statement). [statement = 0, transaction = 1]Basic/Standard/Advanced/Self-Hosted
sql.telemetry.transaction_sampling.max_event_frequency
integer8the max event frequency (events per second) at which we sample transactions for telemetry. If sampling mode is set to 'statement', this setting is ignored. In practice, this means that we only sample a transaction if 1/max_event_frequency seconds have elapsed since the last transaction was sampled.Basic/Standard/Advanced/Self-Hosted
sql.telemetry.transaction_sampling.statement_events_per_transaction.max
integer50the maximum number of statement events to log for every sampled transaction. Note that statements that are logged by force do not adhere to this limit.Basic/Standard/Advanced/Self-Hosted
sql.temp_object_cleaner.cleanup_interval
duration30m0show often to clean up orphaned temporary objectsBasic/Standard/Advanced/Self-Hosted
sql.temp_object_cleaner.wait_interval
duration30m0show long after creation a temporary object will be cleaned upBasic/Standard/Advanced/Self-Hosted
sql.log.all_statements.enabled
(alias: sql.trace.log_statement_execute)
booleanfalseset to true to enable logging of all executed statementsBasic/Standard/Advanced/Self-Hosted
sql.trace.stmt.enable_threshold
duration0senables tracing on all statements; statements executing for longer than this duration will have their trace logged (set to 0 to disable); note that enabling this may have a negative performance impact; this setting applies to individual statements within a transaction and is therefore finer-grained than sql.trace.txn.enable_thresholdBasic/Standard/Advanced/Self-Hosted
sql.trace.txn.enable_threshold
duration0senables transaction traces for transactions exceeding this duration, used with `sql.trace.txn.sample_rate`Basic/Standard/Advanced/Self-Hosted
sql.trace.txn.include_internal.enabled
booleantrueenables tracing internal transactions as well as external workload using sample rate and threshold settingsBasic/Standard/Advanced/Self-Hosted
sql.trace.txn.jaeger_json_output.enabled
booleanfalseenables Jaeger JSON output for transaction traces in logsBasic/Standard/Advanced/Self-Hosted
sql.trace.txn.sample_rate
float1enables probabilistic transaction tracing. It should be used in conjunction with `sql.trace.txn.enable_threshold`. A percentage of transactions between 0 and 1.0 will have tracing enabled, and only those which exceed the configured threshold will be logged.Basic/Standard/Advanced/Self-Hosted
sql.ttl.changefeed_replication.disabled
booleanfalseif true, deletes issued by TTL will not be replicated via changefeeds (this setting will be ignored by changefeeds that have the ignore_disable_changefeed_replication option set; such changefeeds will continue to replicate all TTL deletes)Basic/Standard/Advanced/Self-Hosted
sql.ttl.default_delete_batch_size
integer100default amount of rows to delete in a single query during a TTL jobBasic/Standard/Advanced/Self-Hosted
sql.ttl.default_delete_rate_limit
integer100default delete rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Basic/Standard/Advanced/Self-Hosted
sql.ttl.default_select_batch_size
integer500default amount of rows to select in a single query during a TTL jobBasic/Standard/Advanced/Self-Hosted
sql.ttl.default_select_rate_limit
integer0default select rate limit (rows per second) per node for each TTL job. Use 0 to signify no rate limit.Basic/Standard/Advanced/Self-Hosted
sql.ttl.job.enabled
booleantruewhether the TTL job is enabledBasic/Standard/Advanced/Self-Hosted
sql.txn.read_committed_isolation.enabled
booleantrueset to true to allow transactions to use the READ COMMITTED isolation level if specified by BEGIN/SET commandsBasic/Standard/Advanced/Self-Hosted
sql.txn.repeatable_read_isolation.enabled
(alias: sql.txn.snapshot_isolation.enabled)
booleanfalseset to true to allow transactions to use the REPEATABLE READ isolation level if specified by BEGIN/SET commandsBasic/Standard/Advanced/Self-Hosted
sql.txn_fingerprint_id_cache.capacity
integer100the maximum number of txn fingerprint IDs storedBasic/Standard/Advanced/Self-Hosted
sql.vecindex.stalled_op.timeout
duration100msamount of time before other vector index workers will assist with a stalled background fixupBasic/Standard/Advanced/Self-Hosted
storage.delete_compaction_excise.enabled
booleantrueset to false to direct Pebble to not partially excise sstables in delete-only compactionsAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.ingest_split.enabled
booleantrueset to false to disable ingest-time splitting that lowers write-amplificationAdvanced/Self-Hosted
storage.ingestion.value_blocks.enabled
booleantrueset to true to enable writing of value blocks in ingestion sstablesBasic/Standard/Advanced/Self-Hosted
storage.max_sync_duration
duration20smaximum duration for disk operations; any operations that take longer than this setting trigger a warning log entry or process crashAdvanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.max_sync_duration.fatal.enabled
booleantrueif true, fatal the process when a disk operation exceeds storage.max_sync_durationBasic/Standard/Advanced/Self-Hosted
storage.sstable.compression_algorithm
enumerationfastestdetermines the compression algorithm to use for Pebble stores [snappy = 1, zstd = 2, none = 3, minlz = 4, fastest = 5, balanced = 6, good = 7, fast = 8]Advanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.sstable.compression_algorithm_backup_storage
enumerationfastestdetermines the compression algorithm to use when compressing sstable data blocks for backup row data storage (fast,balanced,good are experimental); [snappy = 1, zstd = 2, none = 3, minlz = 4, fastest = 5, fast = 6, balanced = 7, good = 8]Advanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.sstable.compression_algorithm_backup_transport
enumerationfastestdetermines the compression algorithm to use when compressing sstable data blocks for backup transport (fast,balanced,good are experimental); [snappy = 1, zstd = 2, none = 3, minlz = 4, fastest = 5, fast = 6, balanced = 7, good = 8]Advanced/Self-hosted (read-write); Basic/Standard (read-only)
storage.unhealthy_write_duration
duration20sduration for disk write operations, beyond which the disk will be reported as unhealthy for higher layer actionsAdvanced/Self-Hosted
storage.wal_failover.unhealthy_op_threshold
duration100msthe latency of a WAL write considered unhealthy and triggers a failover to a secondary WAL locationAdvanced/Self-Hosted
timeseries.storage.enabled
booleantrueif set, periodic timeseries data is stored within the cluster; disabling is not recommended unless you are storing the data elsewhereAdvanced/Self-Hosted
timeseries.storage.resolution_10s.ttl
duration240h0m0sthe maximum age of time series data stored at the 10 second resolution. Data older than this is subject to rollup and deletion.Advanced/Self-hosted (read-write); Basic/Standard (read-only)
timeseries.storage.resolution_1m.ttl
duration240h0m0sthe maximum age of time series data stored at the 1 minute resolution. Data older than this is subject to rollup and deletion.Advanced/Self-hosted (read-write); Basic/Standard (read-only)
timeseries.storage.resolution_30m.ttl
duration2160h0m0sthe maximum age of time series data stored at the 30 minute resolution. Data older than this is subject to deletion.Advanced/Self-hosted (read-write); Basic/Standard (read-only)
trace.debug_http_endpoint.enabled
(alias: trace.debug.enable)
booleanfalseif set, traces for recent requests can be seen at https://<ui>/debug/requestsBasic/Standard/Advanced/Self-Hosted
trace.opentelemetry.collector
stringaddress of an OpenTelemetry trace collector to receive traces using the otel gRPC protocol, as <host>:<port>. If no port is specified, 4317 will be used.Basic/Standard/Advanced/Self-Hosted
trace.snapshot.rate
duration0sif non-zero, interval at which background trace snapshots are capturedBasic/Standard/Advanced/Self-Hosted
trace.span_registry.enabled
booleanfalseif set, ongoing traces can be seen at https://<ui>/#/debug/tracezBasic/Standard/Advanced/Self-Hosted
trace.zipkin.collector
stringthe address of a Zipkin instance to receive traces, as <host>:<port>. If no port is specified, 9411 will be used.Basic/Standard/Advanced/Self-Hosted
ui.database_locality_metadata.enabled
booleantrueif enabled shows extended locality data about databases and tables in DB Console which can be expensive to computeBasic/Standard/Advanced/Self-Hosted
ui.default_timezone
stringthe default timezone used to format timestamps in the uiBasic/Standard/Advanced/Self-Hosted
ui.display_timezone
enumerationetc/utcthe timezone used to format timestamps in the ui. This setting is deprecatedand will be removed in a future version. Use the 'ui.default_timezone' setting instead. 'ui.default_timezone' takes precedence over this setting. [etc/utc = 0, america/new_york = 1]Basic/Standard/Advanced/Self-Hosted
version
version26.2set the active cluster version in the format '<major>.<minor>'Basic/Standard/Advanced/Self-Hosted
diff --git a/src/current/_includes/cockroach-generated/release-26.2/sql/aggregates.md b/src/current/_includes/cockroach-generated/release-26.2/sql/aggregates.md new file mode 100644 index 00000000000..5bf74149140 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-26.2/sql/aggregates.md @@ -0,0 +1,599 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_agg(arg1: bool) → bool[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bool[]) → bool[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes) → bytes[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: bytes[]) → bytes[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date) → date[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: date[]) → date[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal) → decimal[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: decimal[]) → decimal[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float) → float[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: float[]) → float[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet) → inet[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: inet[]) → inet[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int) → int[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: int[]) → int[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval) → interval[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: interval[]) → interval[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string) → string[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: string[]) → string[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time) → time[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: time[]) → time[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp) → timestamp[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamp[]) → timestamp[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz) → timestamptz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timestamptz[]) → timestamptz[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid) → uuid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: uuid[]) → uuid[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum) → anyenum[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: anyenum[]) → anyenum[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d) → box2d[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: box2d[]) → box2d[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography) → geography[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geography[]) → geography[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry) → geometry[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: geometry[]) → geometry[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb) → jsonb[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: jsonb[]) → jsonb[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: ltree) → ltree[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: ltree[]) → ltree[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid) → oid[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: oid[]) → oid[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn) → pg_lsn[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: pg_lsn[]) → pg_lsn[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor) → refcursor[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: refcursor[]) → refcursor[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz) → timetz[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: timetz[]) → timetz[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple) → tuple[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: tuple[]) → tuple[][]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit) → varbit[]

Aggregates the selected values into an array.

+		Immutable
array_agg(arg1: varbit[]) → varbit[][]

Aggregates the selected values into an array.

+		Immutable
array_cat_agg(arg1: bool[]) → bool[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: bytes[]) → bytes[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: date[]) → date[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: decimal[]) → decimal[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: float[]) → float[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: inet[]) → inet[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: int[]) → int[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: interval[]) → interval[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: string[]) → string[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: time[]) → time[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamp[]) → timestamp[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timestamptz[]) → timestamptz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: uuid[]) → uuid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: anyenum[]) → anyenum[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: box2d[]) → box2d[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geography[]) → geography[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: geometry[]) → geometry[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: jsonb[]) → jsonb[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: ltree[]) → ltree[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: oid[]) → oid[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: pg_lsn[]) → pg_lsn[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: refcursor[]) → refcursor[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: timetz[]) → timetz[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: tuple[]) → tuple[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
array_cat_agg(arg1: varbit[]) → varbit[]

Unnests the selected arrays into elements that are then aggregated into a single array.

+		Immutable
avg(arg1: decimal) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: float) → float

Calculates the average of the selected values.

+		Immutable
avg(arg1: int) → decimal

Calculates the average of the selected values.

+		Immutable
avg(arg1: interval) → interval

Calculates the average of the selected values.

+		Immutable
bit_and(arg1: int) → int

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_and(arg1: varbit) → varbit

Calculates the bitwise AND of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: int) → int

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bit_or(arg1: varbit) → varbit

Calculates the bitwise OR of all non-null input values, or null if none.

+		Immutable
bool_and(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
bool_or(arg1: bool) → bool

Calculates the boolean value of ORing all selected values.

+		Immutable
concat_agg(arg1: bytes) → bytes

Concatenates all selected values.

+		Immutable
concat_agg(arg1: string) → string

Concatenates all selected values.

+		Immutable
corr(arg1: decimal, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: decimal, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: float, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: decimal) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: float) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
corr(arg1: int, arg2: int) → float

Calculates the correlation coefficient of the selected values.

+		Immutable
count(arg1: anyelement) → int

Calculates the number of selected elements.

+		Immutable
count_rows() → int

Calculates the number of rows.

+		Immutable
covar_pop(arg1: decimal, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: decimal, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: float, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: decimal) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: float) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_pop(arg1: int, arg2: int) → float

Calculates the population covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: decimal, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: float, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: decimal) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: float) → float

Calculates the sample covariance of the selected values.

+		Immutable
covar_samp(arg1: int, arg2: int) → float

Calculates the sample covariance of the selected values.

+		Immutable
every(arg1: bool) → bool

Calculates the boolean value of ANDing all selected values.

+		Immutable
json_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
json_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
jsonb_agg(arg1: anyelement) → jsonb

Aggregates values as a JSON or JSONB array.

+		Stable
jsonb_object_agg(arg1: string, arg2: anyelement) → jsonb

Aggregates values as a JSON or JSONB object.

+		Stable
max(arg1: bool) → bool

Identifies the maximum selected value.

+		Immutable
max(arg1: bytes) → bytes

Identifies the maximum selected value.

+		Immutable
max(arg1: date) → date

Identifies the maximum selected value.

+		Immutable
max(arg1: decimal) → decimal

Identifies the maximum selected value.

+		Immutable
max(arg1: float) → float

Identifies the maximum selected value.

+		Immutable
max(arg1: inet) → inet

Identifies the maximum selected value.

+		Immutable
max(arg1: int) → int

Identifies the maximum selected value.

+		Immutable
max(arg1: interval) → interval

Identifies the maximum selected value.

+		Immutable
max(arg1: string) → string

Identifies the maximum selected value.

+		Immutable
max(arg1: time) → time

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamp) → timestamp

Identifies the maximum selected value.

+		Immutable
max(arg1: timestamptz) → timestamptz

Identifies the maximum selected value.

+		Immutable
max(arg1: uuid) → uuid

Identifies the maximum selected value.

+		Immutable
max(arg1: anyenum) → anyenum

Identifies the maximum selected value.

+		Immutable
max(arg1: box2d) → box2d

Identifies the maximum selected value.

+		Immutable
max(arg1: collatedstring{*}) → collatedstring{*}

Identifies the maximum selected value.

+		Immutable
max(arg1: geography) → geography

Identifies the maximum selected value.

+		Immutable
max(arg1: geometry) → geometry

Identifies the maximum selected value.

+		Immutable
max(arg1: jsonb) → jsonb

Identifies the maximum selected value.

+		Immutable
max(arg1: ltree) → ltree

Identifies the maximum selected value.

+		Immutable
max(arg1: oid) → oid

Identifies the maximum selected value.

+		Immutable
max(arg1: pg_lsn) → pg_lsn

Identifies the maximum selected value.

+		Immutable
max(arg1: timetz) → timetz

Identifies the maximum selected value.

+		Immutable
max(arg1: varbit) → varbit

Identifies the maximum selected value.

+		Immutable
min(arg1: bool) → bool

Identifies the minimum selected value.

+		Immutable
min(arg1: bytes) → bytes

Identifies the minimum selected value.

+		Immutable
min(arg1: date) → date

Identifies the minimum selected value.

+		Immutable
min(arg1: decimal) → decimal

Identifies the minimum selected value.

+		Immutable
min(arg1: float) → float

Identifies the minimum selected value.

+		Immutable
min(arg1: inet) → inet

Identifies the minimum selected value.

+		Immutable
min(arg1: int) → int

Identifies the minimum selected value.

+		Immutable
min(arg1: interval) → interval

Identifies the minimum selected value.

+		Immutable
min(arg1: string) → string

Identifies the minimum selected value.

+		Immutable
min(arg1: time) → time

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamp) → timestamp

Identifies the minimum selected value.

+		Immutable
min(arg1: timestamptz) → timestamptz

Identifies the minimum selected value.

+		Immutable
min(arg1: uuid) → uuid

Identifies the minimum selected value.

+		Immutable
min(arg1: anyenum) → anyenum

Identifies the minimum selected value.

+		Immutable
min(arg1: box2d) → box2d

Identifies the minimum selected value.

+		Immutable
min(arg1: collatedstring{*}) → collatedstring{*}

Identifies the minimum selected value.

+		Immutable
min(arg1: geography) → geography

Identifies the minimum selected value.

+		Immutable
min(arg1: geometry) → geometry

Identifies the minimum selected value.

+		Immutable
min(arg1: jsonb) → jsonb

Identifies the minimum selected value.

+		Immutable
min(arg1: ltree) → ltree

Identifies the minimum selected value.

+		Immutable
min(arg1: oid) → oid

Identifies the minimum selected value.

+		Immutable
min(arg1: pg_lsn) → pg_lsn

Identifies the minimum selected value.

+		Immutable
min(arg1: timetz) → timetz

Identifies the minimum selected value.

+		Immutable
min(arg1: varbit) → varbit

Identifies the minimum selected value.

+		Immutable
percentile_cont(arg1: float) → float

Continuous percentile: returns a float corresponding to the specified fraction in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float) → interval

Continuous percentile: returns an interval corresponding to the specified fraction in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_cont(arg1: float[]) → float[]

Continuous percentile: returns floats corresponding to the specified fractions in the ordering, interpolating between adjacent input floats if needed.

+		Immutable
percentile_cont(arg1: float[]) → interval[]

Continuous percentile: returns intervals corresponding to the specified fractions in the ordering, interpolating between adjacent input intervals if needed.

+		Immutable
percentile_disc(arg1: float) → anyelement

Discrete percentile: returns the first input value whose position in the ordering equals or exceeds the specified fraction.

+		Immutable
percentile_disc(arg1: float[]) → anyelement

Discrete percentile: returns input values whose position in the ordering equals or exceeds the specified fractions.

+		Immutable
regr_avgx(arg1: decimal, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: decimal, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: float, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: decimal) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: float) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgx(arg1: int, arg2: int) → float

Calculates the average of the independent variable (sum(X)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: decimal, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: float, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: decimal) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: float) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_avgy(arg1: int, arg2: int) → float

Calculates the average of the dependent variable (sum(Y)/N).

+		Immutable
regr_count(arg1: decimal, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: decimal, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: float, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: decimal) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: float) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_count(arg1: int, arg2: int) → int

Calculates number of input rows in which both expressions are nonnull.

+		Immutable
regr_intercept(arg1: decimal, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: decimal, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: float, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: decimal) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: float) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_intercept(arg1: int, arg2: int) → float

Calculates y-intercept of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_r2(arg1: decimal, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: decimal, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: float, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: decimal) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: float) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_r2(arg1: int, arg2: int) → float

Calculates square of the correlation coefficient.

+		Immutable
regr_slope(arg1: decimal, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: decimal, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: float, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: decimal) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: float) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_slope(arg1: int, arg2: int) → float

Calculates slope of the least-squares-fit linear equation determined by the (X, Y) pairs.

+		Immutable
regr_sxx(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: decimal, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: float, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: decimal) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: float) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxx(arg1: int, arg2: int) → float

Calculates sum of squares of the independent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: decimal, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: float, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: decimal) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: float) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_sxy(arg1: int, arg2: int) → float

Calculates sum of products of independent times dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: decimal, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: float, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: decimal) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: float) → float

Calculates sum of squares of the dependent variable.

+		Immutable
regr_syy(arg1: int, arg2: int) → float

Calculates sum of squares of the dependent variable.

+		Immutable
sqrdiff(arg1: decimal) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: float) → float

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
sqrdiff(arg1: int) → decimal

Calculates the sum of squared differences from the mean of the selected values.

+		Immutable
st_asmvt(arg1: tuple) → bytes

Generates a Mapbox Vector Tile (MVT) representation of a set of rows. Uses default layer name ‘default’ and extent 4096. Expects a geometry column named ‘geom’ in the input rows.

+		Immutable
st_asmvt(arg1: tuple, arg2: string) → bytes

Generates a Mapbox Vector Tile (MVT) representation of a set of rows with the specified layer name. Uses extent 4096 and expects a geometry column named ‘geom’ in the input rows.

+		Immutable
st_asmvt(arg1: tuple, arg2: string, arg3: int) → bytes

Generates a Mapbox Vector Tile (MVT) representation of a set of rows with the specified layer name and extent. Expects a geometry column named ‘geom’ in the input rows.

+		Immutable
st_asmvt(arg1: tuple, arg2: string, arg3: int, arg4: string) → bytes

Generates a Mapbox Vector Tile (MVT) representation of a set of rows with the specified layer name, extent, and geometry column name.

+		Immutable
st_asmvt(arg1: tuple, arg2: string, arg3: int, arg4: string, arg5: string) → bytes

Generates a Mapbox Vector Tile (MVT) representation of a set of rows with the specified layer name, extent, geometry column name, and feature ID column name.

+		Immutable
st_collect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_extent(arg1: geometry) → box2d

Forms a Box2D that encapsulates all provided geometries.

+		Immutable
st_makeline(arg1: geometry) → geometry

Forms a LineString from Point, MultiPoint or LineStrings. Other shapes will be ignored.

+		Immutable
st_memcollect(arg1: geometry) → geometry

Collects geometries into a GeometryCollection or multi-type as appropriate.

+		Immutable
st_memunion(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
st_union(arg1: geometry) → geometry

Applies a spatial union to the geometries provided.

+		Immutable
stddev(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: decimal) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: float) → float

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_pop(arg1: int) → decimal

Calculates the population standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: decimal) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: float) → float

Calculates the standard deviation of the selected values.

+		Immutable
stddev_samp(arg1: int) → decimal

Calculates the standard deviation of the selected values.

+		Immutable
string_agg(arg1: bytes, arg2: bytes) → bytes

Concatenates all selected values using the provided delimiter.

+		Immutable
string_agg(arg1: string, arg2: string) → string

Concatenates all selected values using the provided delimiter.

+		Immutable
sum(arg1: decimal) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: float) → float

Calculates the sum of the selected values.

+		Immutable
sum(arg1: int) → decimal

Calculates the sum of the selected values.

+		Immutable
sum(arg1: interval) → interval

Calculates the sum of the selected values.

+		Immutable
sum_int(arg1: int) → int

Calculates the sum of the selected values.

+		Immutable
var_pop(arg1: decimal) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: float) → float

Calculates the population variance of the selected values.

+		Immutable
var_pop(arg1: int) → decimal

Calculates the population variance of the selected values.

+		Immutable
var_samp(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
var_samp(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: decimal) → decimal

Calculates the variance of the selected values.

+		Immutable
variance(arg1: float) → float

Calculates the variance of the selected values.

+		Immutable
variance(arg1: int) → decimal

Calculates the variance of the selected values.

+		Immutable
xor_agg(arg1: bytes) → bytes

Calculates the bitwise XOR of the selected values.

+		Immutable
xor_agg(arg1: int) → int

Calculates the bitwise XOR of the selected values.

+		Immutable
+ diff --git a/src/current/_includes/cockroach-generated/release-26.2/sql/functions.md b/src/current/_includes/cockroach-generated/release-26.2/sql/functions.md new file mode 100644 index 00000000000..93e7b8480e2 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-26.2/sql/functions.md @@ -0,0 +1,3732 @@ +### Array functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_append(array: bool[], elem: bool) → bool[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: bytes[], elem: bytes) → bytes[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: date[], elem: date) → date[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: decimal[], elem: decimal) → decimal[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: float[], elem: float) → float[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: inet[], elem: inet) → inet[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: int[], elem: int) → int[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: interval[], elem: interval) → interval[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: string[], elem: string) → string[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: time[], elem: time) → time[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamp[], elem: timestamp) → timestamp[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timestamptz[], elem: timestamptz) → timestamptz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: uuid[], elem: uuid) → uuid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: anyenum[], elem: anyenum) → anyenum[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: box2d[], elem: box2d) → box2d[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geography[], elem: geography) → geography[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: geometry[], elem: geometry) → geometry[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: jsonb[], elem: jsonb) → jsonb[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: ltree[], elem: ltree) → ltree[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: oid[], elem: oid) → oid[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: refcursor[], elem: refcursor) → refcursor[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: timetz[], elem: timetz) → timetz[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: tuple[], elem: tuple) → tuple[]

Appends elem to array, returning the result.

+		Immutable
array_append(array: varbit[], elem: varbit) → varbit[]

Appends elem to array, returning the result.

+		Immutable
array_cat(left: bool[], right: bool[]) → bool[]

Appends two arrays.

+		Immutable
array_cat(left: bytes[], right: bytes[]) → bytes[]

Appends two arrays.

+		Immutable
array_cat(left: date[], right: date[]) → date[]

Appends two arrays.

+		Immutable
array_cat(left: decimal[], right: decimal[]) → decimal[]

Appends two arrays.

+		Immutable
array_cat(left: float[], right: float[]) → float[]

Appends two arrays.

+		Immutable
array_cat(left: inet[], right: inet[]) → inet[]

Appends two arrays.

+		Immutable
array_cat(left: int[], right: int[]) → int[]

Appends two arrays.

+		Immutable
array_cat(left: interval[], right: interval[]) → interval[]

Appends two arrays.

+		Immutable
array_cat(left: string[], right: string[]) → string[]

Appends two arrays.

+		Immutable
array_cat(left: time[], right: time[]) → time[]

Appends two arrays.

+		Immutable
array_cat(left: timestamp[], right: timestamp[]) → timestamp[]

Appends two arrays.

+		Immutable
array_cat(left: timestamptz[], right: timestamptz[]) → timestamptz[]

Appends two arrays.

+		Immutable
array_cat(left: uuid[], right: uuid[]) → uuid[]

Appends two arrays.

+		Immutable
array_cat(left: anyenum[], right: anyenum[]) → anyenum[]

Appends two arrays.

+		Immutable
array_cat(left: box2d[], right: box2d[]) → box2d[]

Appends two arrays.

+		Immutable
array_cat(left: geography[], right: geography[]) → geography[]

Appends two arrays.

+		Immutable
array_cat(left: geometry[], right: geometry[]) → geometry[]

Appends two arrays.

+		Immutable
array_cat(left: jsonb[], right: jsonb[]) → jsonb[]

Appends two arrays.

+		Immutable
array_cat(left: ltree[], right: ltree[]) → ltree[]

Appends two arrays.

+		Immutable
array_cat(left: oid[], right: oid[]) → oid[]

Appends two arrays.

+		Immutable
array_cat(left: pg_lsn[], right: pg_lsn[]) → pg_lsn[]

Appends two arrays.

+		Immutable
array_cat(left: refcursor[], right: refcursor[]) → refcursor[]

Appends two arrays.

+		Immutable
array_cat(left: timetz[], right: timetz[]) → timetz[]

Appends two arrays.

+		Immutable
array_cat(left: tuple[], right: tuple[]) → tuple[]

Appends two arrays.

+		Immutable
array_cat(left: varbit[], right: varbit[]) → varbit[]

Appends two arrays.

+		Immutable
array_length(input: anyelement[], array_dimension: int) → int

Calculates the length of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_lower(input: anyelement[], array_dimension: int) → int

Calculates the minimum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
array_position(array: bool[], elem: bool) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bool[], elem: bool, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: bytes[], elem: bytes) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: bytes[], elem: bytes, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: date[], elem: date) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: date[], elem: date, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: decimal[], elem: decimal) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: decimal[], elem: decimal, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: float[], elem: float) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: float[], elem: float, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: inet[], elem: inet) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: inet[], elem: inet, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: int[], elem: int) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: int[], elem: int, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: interval[], elem: interval) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: interval[], elem: interval, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: string[], elem: string) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: string[], elem: string, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: time[], elem: time) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: time[], elem: time, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timestamp[], elem: timestamp) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamp[], elem: timestamp, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timestamptz[], elem: timestamptz, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: uuid[], elem: uuid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: uuid[], elem: uuid, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: anyenum[], elem: anyenum) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: anyenum[], elem: anyenum, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: box2d[], elem: box2d) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: box2d[], elem: box2d, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: geography[], elem: geography) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geography[], elem: geography, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: geometry[], elem: geometry) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: geometry[], elem: geometry, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: jsonb[], elem: jsonb) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: jsonb[], elem: jsonb, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: ltree[], elem: ltree) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: ltree[], elem: ltree, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: oid[], elem: oid) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: oid[], elem: oid, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: pg_lsn[], elem: pg_lsn, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: refcursor[], elem: refcursor) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: refcursor[], elem: refcursor, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: timetz[], elem: timetz) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: timetz[], elem: timetz, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: tuple[], elem: tuple) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: tuple[], elem: tuple, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_position(array: varbit[], elem: varbit) → int

Return the index of the first occurrence of elem in array.

+		Immutable
array_position(array: varbit[], elem: varbit, start: int) → int

Return the index of the first occurrence of elem in array, with the search begins at start index.

+		Immutable
array_positions(array: bool[], elem: bool) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: bytes[], elem: bytes) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: date[], elem: date) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: decimal[], elem: decimal) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: float[], elem: float) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: inet[], elem: inet) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: int[], elem: int) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: interval[], elem: interval) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: string[], elem: string) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: time[], elem: time) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamp[], elem: timestamp) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timestamptz[], elem: timestamptz) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: uuid[], elem: uuid) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: anyenum[], elem: anyenum) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: box2d[], elem: box2d) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geography[], elem: geography) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: geometry[], elem: geometry) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: jsonb[], elem: jsonb) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: ltree[], elem: ltree) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: oid[], elem: oid) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: pg_lsn[], elem: pg_lsn) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: refcursor[], elem: refcursor) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: timetz[], elem: timetz) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: tuple[], elem: tuple) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_positions(array: varbit[], elem: varbit) → int[]

Returns an array of indexes of all occurrences of elem in array.

+		Immutable
array_prepend(elem: bool, array: bool[]) → bool[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: bytes, array: bytes[]) → bytes[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: date, array: date[]) → date[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: decimal, array: decimal[]) → decimal[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: float, array: float[]) → float[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: inet, array: inet[]) → inet[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: int, array: int[]) → int[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: interval, array: interval[]) → interval[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: string, array: string[]) → string[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: time, array: time[]) → time[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamp, array: timestamp[]) → timestamp[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timestamptz, array: timestamptz[]) → timestamptz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: uuid, array: uuid[]) → uuid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: anyenum, array: anyenum[]) → anyenum[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: box2d, array: box2d[]) → box2d[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geography, array: geography[]) → geography[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: geometry, array: geometry[]) → geometry[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: jsonb, array: jsonb[]) → jsonb[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: ltree, array: ltree[]) → ltree[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: oid, array: oid[]) → oid[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: pg_lsn, array: pg_lsn[]) → pg_lsn[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: refcursor, array: refcursor[]) → refcursor[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: timetz, array: timetz[]) → timetz[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: tuple, array: tuple[]) → tuple[]

Prepends elem to array, returning the result.

+		Immutable
array_prepend(elem: varbit, array: varbit[]) → varbit[]

Prepends elem to array, returning the result.

+		Immutable
array_remove(array: bool[], elem: bool) → bool[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: bytes[], elem: bytes) → bytes[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: date[], elem: date) → date[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: decimal[], elem: decimal) → decimal[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: float[], elem: float) → float[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: inet[], elem: inet) → inet[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: int[], elem: int) → int[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: interval[], elem: interval) → interval[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: string[], elem: string) → string[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: time[], elem: time) → time[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamp[], elem: timestamp) → timestamp[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timestamptz[], elem: timestamptz) → timestamptz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: uuid[], elem: uuid) → uuid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: anyenum[], elem: anyenum) → anyenum[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: box2d[], elem: box2d) → box2d[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geography[], elem: geography) → geography[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: geometry[], elem: geometry) → geometry[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: jsonb[], elem: jsonb) → jsonb[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: ltree[], elem: ltree) → ltree[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: oid[], elem: oid) → oid[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: pg_lsn[], elem: pg_lsn) → pg_lsn[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: refcursor[], elem: refcursor) → refcursor[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: timetz[], elem: timetz) → timetz[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: tuple[], elem: tuple) → tuple[]

Remove from array all elements equal to elem.

+		Immutable
array_remove(array: varbit[], elem: varbit) → varbit[]

Remove from array all elements equal to elem.

+		Immutable
array_replace(array: bool[], toreplace: bool, replacewith: bool) → bool[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: bytes[], toreplace: bytes, replacewith: bytes) → bytes[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: date[], toreplace: date, replacewith: date) → date[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: decimal[], toreplace: decimal, replacewith: decimal) → decimal[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: float[], toreplace: float, replacewith: float) → float[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: inet[], toreplace: inet, replacewith: inet) → inet[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: int[], toreplace: int, replacewith: int) → int[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: interval[], toreplace: interval, replacewith: interval) → interval[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: string[], toreplace: string, replacewith: string) → string[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: time[], toreplace: time, replacewith: time) → time[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamp[], toreplace: timestamp, replacewith: timestamp) → timestamp[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timestamptz[], toreplace: timestamptz, replacewith: timestamptz) → timestamptz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: uuid[], toreplace: uuid, replacewith: uuid) → uuid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: anyenum[], toreplace: anyenum, replacewith: anyenum) → anyenum[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: box2d[], toreplace: box2d, replacewith: box2d) → box2d[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geography[], toreplace: geography, replacewith: geography) → geography[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: geometry[], toreplace: geometry, replacewith: geometry) → geometry[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: jsonb[], toreplace: jsonb, replacewith: jsonb) → jsonb[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: ltree[], toreplace: ltree, replacewith: ltree) → ltree[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: oid[], toreplace: oid, replacewith: oid) → oid[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: pg_lsn[], toreplace: pg_lsn, replacewith: pg_lsn) → pg_lsn[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: refcursor[], toreplace: refcursor, replacewith: refcursor) → refcursor[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: timetz[], toreplace: timetz, replacewith: timetz) → timetz[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: tuple[], toreplace: tuple, replacewith: tuple) → tuple[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_replace(array: varbit[], toreplace: varbit, replacewith: varbit) → varbit[]

Replace all occurrences of toreplace in array with replacewith.

+		Immutable
array_to_string(input: anyelement[], delim: string) → string

Join an array into a string with a delimiter.

+		Stable
array_to_string(input: anyelement[], delimiter: string, null: string) → string

Join an array into a string with a delimiter, replacing NULLs with a null string.

+		Stable
array_upper(input: anyelement[], array_dimension: int) → int

Calculates the maximum value of input on the provided array_dimension. However, because CockroachDB doesn’t yet support multi-dimensional arrays, the only supported array_dimension is 1.

+		Immutable
cardinality(input: anyelement[]) → int

Calculates the number of elements contained in input

+		Immutable
jsonb_array_to_string_array(input: jsonb) → string[]

Convert a JSONB array into a string array.

+		Immutable
string_to_array(str: string, delimiter: string) → string[]

Split a string into components on a delimiter.

+		Immutable
string_to_array(str: string, delimiter: string, null: string) → string[]

Split a string into components on a delimiter with a specified string to consider NULL.

+		Immutable
+ +### BOOL functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Matches case insensetively unescaped with pattern using escape as an escape token.

+		Immutable
inet_contained_by_or_equals(val: inet, container: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_contains_or_equals(container: inet, val: inet) → bool

Test for subnet inclusion or equality, using only the network parts of the addresses. The host part of the addresses is ignored.

+		Immutable
inet_same_family(val: inet, val: inet) → bool

Checks if two IP addresses are of the same IP family.

+		Immutable
like_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
not_ilike_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches case insensetively with pattern using escape as an escape token.

+		Immutable
not_like_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
not_similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Checks whether unescaped not matches with pattern using escape as an escape token.

+		Immutable
+ +### Comparison functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
greatest(anyelement...) → anyelement

Returns the element with the greatest value.

+		Immutable
least(anyelement...) → anyelement

Returns the element with the lowest value.

+		Immutable
num_nonnulls(any...) → int

Returns the number of nonnull arguments.

+		Immutable
num_nulls(any...) → int

Returns the number of null arguments.

+		Immutable
+ +### Cryptographic functions + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crypt(password: string, salt: string) → string

Generates a hash based on a password and salt. The hash algorithm and number of rounds if applicable are encoded in the salt.

+		Immutable
decrypt(data: bytes, key: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
decrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Decrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
digest(data: bytes, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
digest(data: string, type: string) → bytes

Computes a binary hash of the given data. type is the algorithm to use (md5, sha1, sha224, sha256, sha384, or sha512).

+		Immutable
encrypt(data: bytes, key: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
encrypt_iv(data: bytes, key: bytes, iv: bytes, type: string) → bytes

Encrypt data with key using the cipher method specified by type. If the mode is CBC, the provided iv will be used. Otherwise, it will be ignored.

+

The cipher type must have the format <algorithm>[-<mode>][/pad:<padding>] where:

+
    +
  • <algorithm> is aes
    • +
  • <mode> is cbc (default)
    • +
  • <padding> is pkcs (default) or none
    • +
+

This function requires an enterprise license on a CCL distribution.

+		Immutable
gen_random_bytes(count: int) → bytes

Returns count cryptographically strong random bytes. At most 1024 bytes can be extracted at a time.

+		Volatile
gen_salt(type: string) → string

Generates a salt for input into the crypt function using the default number of rounds.

+		Volatile
gen_salt(type: string, iter_count: int) → string

Generates a salt for input into the crypt function using iter_count number of rounds.

+		Volatile
hmac(data: bytes, key: bytes, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
hmac(data: string, key: string, type: string) → bytes

Calculates hashed MAC for data with key key. type is the same as in digest().

+		Immutable
+ +### DECIMAL functions + + + + + + +
Function → ReturnsDescriptionVolatility
hlc_to_timestamp(hlc: decimal) → timestamptz

Returns a TimestampTZ representation of a CockroachDB HLC in decimal form.

+

Note that a TimestampTZ has less precision than a CockroachDB HLC. It is intended as +a convenience function to display HLCs in a print-friendly form. Use the decimal +value if you rely on the HLC for accuracy.

+		Immutable
to_number(value: string, format: string) → decimal

Convert a string to a numeric using the given format.

+		Stable
+ +### Date and time functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
age(end: timestamptz, begin: timestamptz) → interval

Calculates the interval between begin and end, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use the timestamptz subtraction operator.

+		Immutable
age(val: timestamptz) → interval

Calculates the interval between val and the current time, normalized into years, months and days.

+

Note this may not be an accurate time span since years and months are normalized +from days, and years and months are out of context. To avoid normalizing days into +months and years, use now() - timestamptz.

+		Stable
clock_timestamp() → timestamp

Returns the current system time on one of the cluster nodes.

+		Volatile
clock_timestamp() → timestamptz

Returns the current system time on one of the cluster nodes.

+		Volatile
current_date() → date

Returns the date of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_timestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
current_timestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
date_part(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
date_part(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
date_part(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
date_trunc(element: string, input: date) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: interval) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: time) → interval

Truncates input to precision element. Sets all fields that are less +significant than element to zero.

+

Compatible elements: hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamp) → timestamp

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Immutable
date_trunc(element: string, input: timestamptz) → timestamptz

Truncates input to precision element. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
date_trunc(element: string, input: timestamptz, timezone: string) → timestamptz

Truncates input to precision element in the specified timezone. Sets all fields that are less +significant than element to zero (or one, for day and month)

+

Compatible elements: millennium, century, decade, year, quarter, month, +week, day, hour, minute, second, millisecond, microsecond.

+		Stable
experimental_follower_read_timestamp() → timestamptz

Same as follower_read_timestamp. This name is deprecated.

+		Volatile
experimental_strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
experimental_strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
extract(element: string, input: date) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: interval) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, +month, day, hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: time) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamp) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch

+		Immutable
extract(element: string, input: timestamptz) → float

Extracts element from input.

+

Compatible elements: millennium, century, decade, year, isoyear, +quarter, month, week, dayofweek, isodow, dayofyear, julian, +hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Stable
extract(element: string, input: timetz) → float

Extracts element from input.

+

Compatible elements: hour, minute, second, millisecond, microsecond, epoch, +timezone, timezone_hour, timezone_minute

+		Immutable
extract_duration(element: string, input: interval) → int

Extracts element from input. +Compatible elements: hour, minute, second, millisecond, microsecond. +This is deprecated in favor of extract which supports duration.

+		Immutable
follower_read_timestamp() → timestamptz

Returns a timestamp which is very likely to be safe to perform +against a follower replica.

+

This function is intended to be used with an AS OF SYSTEM TIME clause to perform +historical reads against a time which is recent but sufficiently old for reads +to be performed against the closest replica as opposed to the currently +leaseholder for a given range.

+

Note that this function requires an enterprise license on a CCL distribution to +return a result that is less likely the closest replica. It is otherwise +hardcoded as -4.8s from the statement time, which may not result in reading from the +nearest replica.

+		Volatile
localtimestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
localtimestamp(precision: int) → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtimestamp(precision: int) → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
make_date(year: int, month: int, day: int) → date

Create date (formatted according to ISO 8601) from year, month, and day fields (negative years signify BC).

+		Immutable
make_timestamp(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamp

Create timestamp (formatted according to ISO 8601) from year, month, day, hour, minute, and seconds fields (negative years signify BC).

+		Immutable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
make_timestamptz(year: int, month: int, day: int, hour: int, min: int, sec: float, timezone: string) → timestamptz

Create timestamp (formatted according to ISO 8601) with time zone from year, month, day, hour, minute and seconds fields (negative years signify BC). If timezone is not specified, the current time zone is used.

+		Stable
now() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
now() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
overlaps(s1: date, e1: date, s1: date, e2: date) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: date, e1: interval, s1: date, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: interval, s1: time, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: time, e1: time, s1: time, e2: time) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: interval, s1: timestamp, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamp, e1: timestamp, s1: timestamp, e2: timestamp) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timestamptz, e1: interval, s1: timestamptz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Stable
overlaps(s1: timestamptz, e1: timestamptz, s1: timestamptz, e2: timestamptz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: interval, s1: timetz, e2: interval) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
overlaps(s1: timetz, e1: timetz, s1: timetz, e2: timetz) → bool

Returns if two time periods (defined by their endpoints) overlap.

+		Immutable
statement_timestamp() → timestamp

Returns the start time of the current statement.

+		Stable
statement_timestamp() → timestamptz

Returns the start time of the current statement.

+		Stable
strftime(input: date, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamp, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strftime(input: timestamptz, extract_format: string) → string

From input, extracts and formats the time as identified in extract_format using standard strftime notation (though not all formatting is supported).

+		Immutable
strptime(input: string, format: string) → timestamptz

Returns input as a timestamptz using format (which uses standard strptime formatting).

+		Immutable
timeofday() → string

Returns the current system time on one of the cluster nodes as a string.

+		Stable
timezone(timezone: string, time: time) → timetz

Treat given time without time zone as located in the specified time zone.

+		Stable
timezone(timezone: string, timestamp: timestamp) → timestamptz

Treat given time stamp without time zone as located in the specified time zone.

+		Immutable
timezone(timezone: string, timestamptz: timestamptz) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Immutable
timezone(timezone: string, timestamptz_string: string) → timestamp

Convert given time stamp with time zone to the new time zone, with no time zone designation.

+		Stable
timezone(timezone: string, timetz: timetz) → timetz

Convert given time with time zone to the new time zone.

+		Stable
to_char(date: date) → string

Convert an date to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(date: date, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_char(interval: interval) → string

Convert an interval to a string assuming the Postgres IntervalStyle.

+		Immutable
to_char(interval: interval, format: string) → string

Convert an interval to a string using the given format.

+		Stable
to_char(number: decimal, format: string) → string

Convert a decimal to a string using the given format.

+		Stable
to_char(number: float, format: string) → string

Convert a float to a string using the given format.

+		Stable
to_char(number: int, format: string) → string

Convert an integer to a string using the given format.

+		Stable
to_char(timestamp: timestamp) → string

Convert an timestamp to a string assuming the ISO, MDY DateStyle.

+		Immutable
to_char(timestamp: timestamp, format: string) → string

Convert an timestamp to a string using the given format.

+		Stable
to_char(timestamptz: timestamptz, format: string) → string

Convert a timestamp with time zone to a string using the given format.

+		Stable
to_date(date_string: string, format: string) → date

Convert a string to a date using the given format.

+		Stable
to_timestamp(date_string: string, format: string) → timestamptz

Convert a string to a timestamp with time zone using the given format.

+		Stable
to_timestamp(timestamp: float) → timestamptz

Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to timestamp with time zone.

+		Immutable
transaction_timestamp() → date

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamp

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+		Stable
transaction_timestamp() → timestamptz

Returns the time of the current transaction.

+

The value is based on a timestamp picked when the transaction starts +and which stays constant throughout the transaction. This timestamp +has no relationship with the commit order of concurrent transactions.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
with_max_staleness(max_staleness: interval) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_max_staleness(max_staleness: interval, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp within the staleness +bound that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
with_min_timestamp(min_timestamp: timestamptz, nearest_only: bool) → timestamptz

When used in the AS OF SYSTEM TIME clause of an single-statement, +read-only transaction, CockroachDB chooses the newest timestamp before the min_timestamp +that allows execution of the reads at the nearest available replica without blocking.

+

If nearest_only is set to true, reads that cannot be served using the nearest +available replica will error.

+

Note this function requires an enterprise license on a CCL distribution.

+		Volatile
+ +### Enum functions + + + + + + + + +
Function → ReturnsDescriptionVolatility
enum_first(val: anyenum) → anyenum

Returns the first value of the input enum type.

+		Stable
enum_last(val: anyenum) → anyenum

Returns the last value of the input enum type.

+		Stable
enum_range(lower: anyenum, upper: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array between the two arguments (inclusive).

+		Stable
enum_range(val: anyenum) → anyenum[]

Returns all values of the input enum in an ordered array.

+		Stable
+ +### FLOAT functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abs(val: decimal) → decimal

Calculates the absolute value of val.

+		Immutable
abs(val: float) → float

Calculates the absolute value of val.

+		Immutable
abs(val: int) → int

Calculates the absolute value of val.

+		Immutable
acos(val: float) → float

Calculates the inverse cosine of val.

+		Immutable
acosd(val: float) → float

Calculates the inverse cosine of val with the result in degrees

+		Immutable
acosh(val: float) → float

Calculates the inverse hyperbolic cosine of val.

+		Immutable
asin(val: float) → float

Calculates the inverse sine of val.

+		Immutable
asind(val: float) → float

Calculates the inverse sine of val with the result in degrees.

+		Immutable
asinh(val: float) → float

Calculates the inverse hyperbolic sine of val.

+		Immutable
atan(val: float) → float

Calculates the inverse tangent of val.

+		Immutable
atan2(x: float, y: float) → float

Calculates the inverse tangent of x/y.

+		Immutable
atan2d(x: float, y: float) → float

Calculates the inverse tangent of x/y with the result in degrees

+		Immutable
atand(val: float) → float

Calculates the inverse tangent of val with the result in degrees.

+		Immutable
atanh(val: float) → float

Calculates the inverse hyperbolic tangent of val.

+		Immutable
cbrt(val: decimal) → decimal

Calculates the cube root (∛) of val.

+		Immutable
cbrt(val: float) → float

Calculates the cube root (∛) of val.

+		Immutable
ceil(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceil(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: decimal) → decimal

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: float) → float

Calculates the smallest integer not smaller than val.

+		Immutable
ceiling(val: int) → float

Calculates the smallest integer not smaller than val.

+		Immutable
cos(val: float) → float

Calculates the cosine of val.

+		Immutable
cosd(val: float) → float

Calculates the cosine of val where val is in degrees.

+		Immutable
cosh(val: float) → float

Calculates the hyperbolic cosine of val.

+		Immutable
cot(val: float) → float

Calculates the cotangent of val.

+		Immutable
cotd(val: float) → float

Calculates the cotangent of val where val is in degrees.

+		Immutable
degrees(val: float) → float

Converts val as a radian value to a degree value.

+		Immutable
div(x: decimal, y: decimal) → decimal

Calculates the integer quotient of x/y.

+		Immutable
div(x: float, y: float) → float

Calculates the integer quotient of x/y.

+		Immutable
div(x: int, y: int) → int

Calculates the integer quotient of x/y.

+		Immutable
exp(val: decimal) → decimal

Calculates e ^ val.

+		Immutable
exp(val: float) → float

Calculates e ^ val.

+		Immutable
floor(val: decimal) → decimal

Calculates the largest integer not greater than val.

+		Immutable
floor(val: float) → float

Calculates the largest integer not greater than val.

+		Immutable
floor(val: int) → float

Calculates the largest integer not greater than val.

+		Immutable
isnan(val: decimal) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
isnan(val: float) → bool

Returns true if val is NaN, false otherwise.

+		Immutable
ln(val: decimal) → decimal

Calculates the natural log of val.

+		Immutable
ln(val: float) → float

Calculates the natural log of val.

+		Immutable
log(b: decimal, x: decimal) → decimal

Calculates the base b log of val.

+		Immutable
log(b: float, x: float) → float

Calculates the base b log of val.

+		Immutable
log(val: decimal) → decimal

Calculates the base 10 log of val.

+		Immutable
log(val: float) → float

Calculates the base 10 log of val.

+		Immutable
mod(x: decimal, y: decimal) → decimal

Calculates x%y.

+		Immutable
mod(x: float, y: float) → float

Calculates x%y.

+		Immutable
mod(x: int, y: int) → int

Calculates x%y.

+		Immutable
pi() → float

Returns the value for pi (3.141592653589793).

+		Immutable
pow(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
pow(x: float, y: float) → float

Calculates x^y.

+		Immutable
pow(x: int, y: int) → int

Calculates x^y.

+		Immutable
power(x: decimal, y: decimal) → decimal

Calculates x^y.

+		Immutable
power(x: float, y: float) → float

Calculates x^y.

+		Immutable
power(x: int, y: int) → int

Calculates x^y.

+		Immutable
radians(val: float) → float

Converts val as a degree value to a radians value.

+		Immutable
random() → float

Returns a random floating-point number between 0 (inclusive) and 1 (exclusive). Note that the value contains at most 53 bits of randomness.

+		Volatile
round(input: decimal, decimal_accuracy: int) → decimal

Keeps decimal_accuracy number of figures to the right of the zero position in input using half away from zero rounding. If decimal_accuracy is not in the range -2^31…(2^31-1), the results are undefined.

+		Immutable
round(input: float, decimal_accuracy: int) → float

Keeps decimal_accuracy number of figures to the right of the zero position in input using half to even (banker’s) rounding.

+		Immutable
round(val: decimal) → decimal

Rounds val to the nearest integer, half away from zero: round(+/-2.4) = +/-2, round(+/-2.5) = +/-3.

+		Immutable
round(val: float) → float

Rounds val to the nearest integer using half to even (banker’s) rounding.

+		Immutable
setseed(seed: float) → void

Sets the seed for subsequent random() calls in this session (value between -1.0 and 1.0, inclusive). There are no guarantees as to how this affects the seed of random() calls that appear in the same query as setseed().

+		Volatile
sign(val: decimal) → decimal

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: float) → float

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sign(val: int) → int

Determines the sign of val: 1 for positive; 0 for 0 values; -1 for negative.

+		Immutable
sin(val: float) → float

Calculates the sine of val.

+		Immutable
sind(val: float) → float

Calculates the sine of val where val is in degrees.

+		Immutable
sinh(val: float) → float

Calculates the hyperbolic sine of val.

+		Immutable
sqrt(val: decimal) → decimal

Calculates the square root of val.

+		Immutable
sqrt(val: float) → float

Calculates the square root of val.

+		Immutable
tan(val: float) → float

Calculates the tangent of val.

+		Immutable
tand(val: float) → float

Calculates the tangent of val where val is in degrees.

+		Immutable
tanh(val: float) → float

Calculates the hyperbolic tangent of val.

+		Immutable
trunc(val: decimal) → decimal

Truncates the decimal values of val.

+		Immutable
trunc(val: decimal, scale: int) → decimal

Truncate val to scale decimal places

+		Immutable
trunc(val: float) → float

Truncates the decimal values of val.

+		Immutable
+ +### Full Text Search functions + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
phraseto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The <-> operator is inserted between each token in the input.

+		Immutable
phraseto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The <-> operator is inserted between each token in the input.

+		Stable
plainto_tsquery(config: string, text: string) → tsquery

Converts text to a tsquery, normalizing words according to the specified configuration. The & operator is inserted between each token in the input.

+		Immutable
plainto_tsquery(text: string) → tsquery

Converts text to a tsquery, normalizing words according to the default configuration. The & operator is inserted between each token in the input.

+		Stable
to_tsquery(config: string, text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the specified configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Immutable
to_tsquery(text: string) → tsquery

Converts the input text into a tsquery by normalizing each word in the input according to the default configuration. The input must already be formatted like a tsquery, in other words, subsequent tokens must be connected by a tsquery operator (&, |, <->, !).

+		Stable
to_tsvector(config: string, text: string) → tsvector

Converts text to a tsvector, normalizing words according to the specified configuration. Position information is included in the result.

+		Immutable
to_tsvector(text: string) → tsvector

Converts text to a tsvector, normalizing words according to the default configuration. Position information is included in the result.

+		Stable
ts_parse(parser_name: string, document: string) → tuple{int AS tokid, string AS token}

ts_parse parses the given document and returns a series of records, one for each token produced by parsing. Each record includes a tokid showing the assigned token type and a token which is the text of the token.

+		Stable
ts_rank(vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
ts_rank(weights: float[], vector: tsvector, query: tsquery, normalization: int) → float4

Ranks vectors based on the frequency of their matching lexemes.

+		Immutable
+ +### Fuzzy String Matching functions + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
daitch_mokotoff(source: string) → string[]

Returns an array of Daitch-Mokotoff soundex codes for the input string.

+		Immutable
dmetaphone(source: string) → string

Returns the primary Double Metaphone code for the input string.

+		Immutable
dmetaphone_alt(source: string) → string

Returns the alternate Double Metaphone code for the input string.

+		Immutable
levenshtein(source: string, target: string) → int

Calculates the Levenshtein distance between two strings. Maximum input length is 255 characters.

+		Immutable
levenshtein(source: string, target: string, ins_cost: int, del_cost: int, sub_cost: int) → int

Calculates the Levenshtein distance between two strings. The cost parameters specify how much to charge for each edit operation. Maximum input length is 255 characters.

+		Immutable
levenshtein_less_equal(source: string, target: string, ins_cost: int, del_cost: int, sub_cost: int, max_d: int) → int

Calculates the Levenshtein distance between two strings. The cost parameters specify how much to charge for each edit operation. If actual distance is less or equal then max_d, then it returns the distance. Otherwise this function returns a value greater than max_d. The maximum length of the input strings is 255 characters.

+		Immutable
levenshtein_less_equal(source: string, target: string, max_d: int) → int

Calculates the Levenshtein distance between two strings. If actual distance is less or equal then max_d, then it returns the distance. Otherwise this function returns a value greater than max_d. The maximum length of the input strings is 255 characters.

+		Immutable
metaphone(source: string, max_output_length: int) → string

Convert a string to its Metaphone code. Maximum input length is 255 characters

+		Immutable
soundex(source: string) → string

Convert a string to its Soundex code.

+		Immutable
+ +### ID generation functions + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
experimental_uuid_v4() → bytes

Returns a UUID.

+		Volatile
gen_random_ulid() → uuid

Generates a random ULID and returns it as a value of UUID type.

+		Volatile
gen_random_uuid() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
unique_rowid() → int

Returns a unique ID used by CockroachDB to generate unique row IDs if a Primary Key isn’t defined for the table. The value is a combination of the insert timestamp and the ID of the node executing the statement, which guarantees this combination is globally unique. However, there can be gaps and the order is not completely guaranteed.

+		Volatile
unordered_unique_rowid() → int

Returns a unique ID. The value is a combination of the insert timestamp (bit-reversed) and the ID of the node executing the statement, which guarantees this combination is globally unique. The way it is generated is statistically likely to not have any ordering relative to previously generated values.

+		Volatile
uuid_generate_v1() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. To avoid exposing the server’s real MAC address, this uses a random MAC address and a timestamp. Essentially, this is an alias for uuid_generate_v1mc.

+		Volatile
uuid_generate_v1mc() → uuid

Generates a version 1 UUID, and returns it as a value of UUID type. This uses a random MAC address and a timestamp.

+		Volatile
uuid_generate_v3(namespace: uuid, name: string) → uuid

Generates a version 3 UUID in the given namespace using the specified input name, with md5 as the hashing method. The namespace should be one of the special constants produced by the uuid_ns_*() functions.

+		Immutable
uuid_generate_v4() → uuid

Generates a random version 4 UUID, and returns it as a value of UUID type.

+		Volatile
uuid_generate_v5(namespace: uuid, name: string) → uuid

Generates a version 5 UUID in the given namespace using the specified input name. This is similar to a version 3 UUID, except it uses SHA-1 for hashing.

+		Immutable
uuid_nil() → uuid

Returns a nil UUID constant.

+		Immutable
uuid_ns_dns() → uuid

Returns a constant designating the DNS namespace for UUIDs.

+		Immutable
uuid_ns_oid() → uuid

Returns a constant designating the ISO object identifier (OID) namespace for UUIDs. These are unrelated to the OID type used internally in the database.

+		Immutable
uuid_ns_url() → uuid

Returns a constant designating the URL namespace for UUIDs.

+		Immutable
uuid_ns_x500() → uuid

Returns a constant designating the X.500 distinguished name (DN) namespace for UUIDs.

+		Immutable
uuid_v4() → bytes

Returns a UUID.

+		Volatile
+ +### INET functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
abbrev(val: inet) → string

Converts the combined IP address and prefix length to an abbreviated display format as text.For INET types, this will omit the prefix length if it’s not the default (32 or IPv4, 128 for IPv6)

+

For example, abbrev('192.168.1.2/24') returns '192.168.1.2/24'

+		Immutable
broadcast(val: inet) → inet

Gets the broadcast address for the network address represented by the value.

+

For example, broadcast('192.168.1.2/24') returns '192.168.1.255/24'

+		Immutable
family(val: inet) → int

Extracts the IP family of the value; 4 for IPv4, 6 for IPv6.

+

For example, family('::1') returns 6

+		Immutable
host(val: inet) → string

Extracts the address part of the combined address/prefixlen value as text.

+

For example, host('192.168.1.2/16') returns '192.168.1.2'

+		Immutable
hostmask(val: inet) → inet

Creates an IP host mask corresponding to the prefix length in the value.

+

For example, hostmask('192.168.1.2/16') returns '0.0.255.255'

+		Immutable
masklen(val: inet) → int

Retrieves the prefix length stored in the value.

+

For example, masklen('192.168.1.2/16') returns 16

+		Immutable
netmask(val: inet) → inet

Creates an IP network mask corresponding to the prefix length in the value.

+

For example, netmask('192.168.1.2/16') returns '255.255.0.0'

+		Immutable
set_masklen(val: inet, prefixlen: int) → inet

Sets the prefix length of val to prefixlen.

+

For example, set_masklen('192.168.1.2', 16) returns '192.168.1.2/16'.

+		Immutable
+ +### INT functions + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
crc32c(bytes...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32c(string...) → int

Calculates the CRC-32 hash using the Castagnoli polynomial.

+		Leakproof
crc32ieee(bytes...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
crc32ieee(string...) → int

Calculates the CRC-32 hash using the IEEE polynomial.

+		Leakproof
fnv32(bytes...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32(string...) → int

Calculates the 32-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv32a(bytes...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv32a(string...) → int

Calculates the 32-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64(bytes...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64(string...) → int

Calculates the 64-bit FNV-1 hash value of a set of values.

+		Leakproof
fnv64a(bytes...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
fnv64a(string...) → int

Calculates the 64-bit FNV-1a hash value of a set of values.

+		Leakproof
width_bucket(operand: decimal, b1: decimal, b2: decimal, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2. Returns 0 or count+1 for an input outside that range.

+		Immutable
width_bucket(operand: int, b1: int, b2: int, count: int) → int

return the bucket number to which operand would be assigned in a histogram having count equal-width buckets spanning the range b1 to b2.

+		Immutable
width_bucket(operand: anyelement, thresholds: anyelement[]) → int

return the bucket number to which operand would be assigned given an array listing the lower bounds of the buckets; returns 0 for an input less than the first lower bound; the thresholds array must be sorted, smallest first, or unexpected results will be obtained

+		Immutable
+ +### JSONB functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
array_to_json(array: anyelement[]) → jsonb

Returns the array as JSON or JSONB.

+		Stable
array_to_json(array: anyelement[], pretty_bool: bool) → jsonb

Returns the array as JSON or JSONB.

+		Stable
json_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
json_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
json_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
json_build_array(any...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
json_build_object(any...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
json_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
json_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
json_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
json_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
json_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
json_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
json_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
json_remove_path(val: jsonb, path: string[]) → jsonb

Remove the specified path from the JSON object.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
json_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
json_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
json_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
json_valid(string: string) → bool

Returns whether the given string is a valid JSON or not

+		Immutable
jsonb_array_elements(input: jsonb) → jsonb

Expands a JSON array to a set of JSON values.

+		Immutable
jsonb_array_elements_text(input: jsonb) → string

Expands a JSON array to a set of text values.

+		Immutable
jsonb_array_length(json: jsonb) → int

Returns the number of elements in the outermost JSON or JSONB array.

+		Immutable
jsonb_build_array(any...) → jsonb

Builds a possibly-heterogeneously-typed JSON or JSONB array out of a variadic argument list.

+		Stable
jsonb_build_object(any...) → jsonb

Builds a JSON object out of a variadic argument list.

+		Stable
jsonb_each(input: jsonb) → tuple{string AS key, jsonb AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs.

+		Immutable
jsonb_each_text(input: jsonb) → tuple{string AS key, string AS value}

Expands the outermost JSON or JSONB object into a set of key/value pairs. The returned values will be of type text.

+		Immutable
jsonb_exists_any(json: jsonb, array: string[]) → bool

Returns whether any of the strings in the text array exist as top-level keys or array elements

+		Immutable
jsonb_extract_path(jsonb, string...) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_extract_path_text(jsonb, string...) → string

Returns the JSON value as text pointed to by the variadic arguments.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments. new_val will be inserted before path target.

+		Immutable
jsonb_insert(target: jsonb, path: string[], new_val: jsonb, insert_after: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If insert_after is true (default is false), new_val will be inserted after path target.

+		Immutable
jsonb_object(keys: string[], values: string[]) → jsonb

This form of json_object takes keys and values pairwise from two separate arrays. In all other respects it is identical to the one-argument form.

+		Immutable
jsonb_object(texts: string[]) → jsonb

Builds a JSON or JSONB object out of a text array. The array must have exactly one dimension with an even number of members, in which case they are taken as alternating key/value pairs.

+		Immutable
jsonb_populate_record(base: anyelement, from_json: jsonb) → anyelement

Expands the object in from_json to a row whose columns match the record type defined by base.

+		Stable
jsonb_populate_recordset(base: anyelement, from_json: jsonb) → anyelement

Expands the outermost array of objects in from_json to a set of rows whose columns match the record type defined by base

+		Stable
jsonb_pretty(val: jsonb) → string

Returns the given JSON value as a STRING indented and with newlines.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb) → jsonb

Returns the JSON value pointed to by the variadic arguments.

+		Immutable
jsonb_set(val: jsonb, path: string[], to: jsonb, create_missing: bool) → jsonb

Returns the JSON value pointed to by the variadic arguments. If create_missing is false, new keys will not be inserted to objects and values will not be prepended or appended to arrays.

+		Immutable
jsonb_strip_nulls(from_json: jsonb) → jsonb

Returns from_json with all object fields that have null values omitted. Other null values are untouched.

+		Immutable
jsonb_typeof(val: jsonb) → string

Returns the type of the outermost JSON value as a text string.

+		Immutable
row_to_json(row: tuple) → jsonb

Returns the row as a JSON object.

+		Stable
to_json(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
to_jsonb(val: anyelement) → jsonb

Returns the value as JSON or JSONB.

+		Stable
+ +### Jsonpath functions + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
jsonb_path_exists(target: jsonb, path: jsonpath) → bool

Checks whether the JSON path returns any item for the specified JSON value.

+		Immutable
jsonb_path_exists(target: jsonb, path: jsonpath, vars: jsonb) → bool

Checks whether the JSON path returns any item for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named +values to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_exists(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → bool

Checks whether the JSON path returns any item for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named +values to be substituted into the jsonpath expression. If the silent +argument is true, the function suppresses the following errors: +missing object field or array element, unexpected JSON item type, +datetime and numeric errors.

+		Immutable
jsonb_path_match(target: jsonb, path: jsonpath) → bool

Returns the SQL boolean result of a JSON path predicate check +for the specified JSON value. (This is useful only with predicate check +expressions, not SQL-standard JSON path expressions, since it will +either fail or return NULL if the path result is not a single boolean +value.)

+		Immutable
jsonb_path_match(target: jsonb, path: jsonpath, vars: jsonb) → bool

Returns the SQL boolean result of a JSON path predicate check +for the specified JSON value. (This is useful only with predicate check +expressions, not SQL-standard JSON path expressions, since it will +either fail or return NULL if the path result is not a single boolean +value.) The vars argument must be a JSON object, and its fields provide +named values to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_match(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → bool

Returns the SQL boolean result of a JSON path predicate check +for the specified JSON value. (This is useful only with predicate check +expressions, not SQL-standard JSON path expressions, since it will +either fail or return NULL if the path result is not a single boolean +value.) The vars argument must be a JSON object, and its fields provide +named values to be substituted into the jsonpath expression. If the +silent argument is true, the function suppresses the following errors: +missing object field or array element, unexpected JSON item type, +datetime and numeric errors.

+		Immutable
jsonb_path_query(target: jsonb, path: jsonpath) → jsonb

Returns all JSON items returned by the JSON path for the specified JSON value.

+		Immutable
jsonb_path_query(target: jsonb, path: jsonpath, vars: jsonb) → jsonb

Returns all JSON items returned by the JSON path for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_query(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → jsonb

Returns all JSON items returned by the JSON path for the specified JSON value. +The vars argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression. If the silent argument is true, +the function suppresses the following errors: missing object field or array +element, unexpected JSON item type, datetime and numeric errors.

+		Immutable
jsonb_path_query_array(target: jsonb, path: jsonpath) → jsonb

Returns all JSON items returned by the JSON path for the +specified JSON value, as a JSON array.

+		Immutable
jsonb_path_query_array(target: jsonb, path: jsonpath, vars: jsonb) → jsonb

Returns all JSON items returned by the JSON path for the +specified JSON value, as a JSON array. The vars argument must be a +JSON object, and its fields provide named values to be substituted +into the jsonpath expression.

+		Immutable
jsonb_path_query_array(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → jsonb

Returns all JSON items returned by the JSON path for the +specified JSON value, as a JSON array. The vars argument must be a +JSON object, and its fields provide named values to be substituted +into the jsonpath expression. If the silent argument is true, the +function suppresses the following errors: missing object field or +array element, unexpected JSON item type, datetime and numeric errors.

+		Immutable
jsonb_path_query_first(target: jsonb, path: jsonpath) → jsonb

Returns the first JSON item returned by the JSON path for the +specified JSON value, or NULL if there are no results.

+		Immutable
jsonb_path_query_first(target: jsonb, path: jsonpath, vars: jsonb) → jsonb

Returns the first JSON item returned by the JSON path for the +specified JSON value, or NULL if there are no results. The vars +argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression.

+		Immutable
jsonb_path_query_first(target: jsonb, path: jsonpath, vars: jsonb, silent: bool) → jsonb

Returns the first JSON item returned by the JSON path for the +specified JSON value, or NULL if there are no results. The vars +argument must be a JSON object, and its fields provide named values +to be substituted into the jsonpath expression. If the silent argument is true, the +function suppresses the following errors: missing object field or +array element, unexpected JSON item type, datetime and numeric errors.

+		Immutable
+ +### LTree functions + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
index(a: ltree, b: ltree) → int

position of first occurrence of b in a; -1 if not found

+		Immutable
index(a: ltree, b: ltree, offset: int) → int

position of first occurrence of b in a, starting at offset; -1 if not found

+		Immutable
lca(ltree, ltree, ltree...) → ltree

lowest common ancestor, i.e., longest common prefix of paths

+		Immutable
lca(ltree[]: ltree[]) → ltree

lowest common ancestor, i.e., longest common prefix of paths

+		Immutable
ltree2text(ltree: ltree) → string

cast ltree to text

+		Immutable
nlevel(ltree: ltree) → int

number of labels in path ltree

+		Immutable
subltree(ltree: ltree, start: int, end: int) → ltree

subpath of ltree from position start to position end-1 (counting from 0)

+		Immutable
subpath(ltree: ltree, offset: int) → ltree

subpath of ltree starting at position offset, extending to end of path. If offset is negative, subpath starts that far from the end of the path.

+		Immutable
subpath(ltree: ltree, offset: int, length: int) → ltree

subpath of ltree starting at position offset, length length. If offset is negative, subpath starts that far from the end of the path. If length is negative, leaves that many labels off the end of the path.

+		Immutable
text2ltree(text: string) → ltree

cast text to ltree

+		Immutable
+ +### Multi-region functions + + + + + + + +
Function → ReturnsDescriptionVolatility
default_to_database_primary_region(val: string) → string

Returns the given region if the region has been added to the current database. +Otherwise, this will return the primary region of the current database. +This will error if the current database is not a multi-region database.

+		Stable
gateway_region() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
rehome_row() → string

Returns the region of the connection’s current node as defined by +the locality flag on node startup. Returns an error if no region is set.

+		Stable
+ +### PGVector functions + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cosine_distance(v1: vector, v2: vector) → float

Returns the cosine distance between the two vectors.

+		Immutable
inner_product(v1: vector, v2: vector) → float

Returns the inner product between the two vectors.

+		Immutable
l1_distance(v1: vector, v2: vector) → float

Returns the Manhattan distance between the two vectors.

+		Immutable
l2_distance(v1: vector, v2: vector) → float

Returns the Euclidean distance between the two vectors.

+		Immutable
vector_dims(vector: vector) → int

Returns the number of the dimensions in the vector.

+		Immutable
vector_norm(vector: vector) → float

Returns the Euclidean norm of the vector.

+		Immutable
+ +### STRING[] functions + + + + + + +
Function → ReturnsDescriptionVolatility
regexp_split_to_array(string: string, pattern: string) → string[]

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_array(string: string, pattern: string, flags: string) → string[]

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
+ +### Sequence functions + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
currval(sequence_name: string) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
currval(sequence_name: regclass) → int

Returns the latest value obtained with nextval for this sequence in this session.

+		Volatile
lastval() → int

Return value most recently obtained with nextval in this session.

+		Volatile
nextval(sequence_name: string) → int

Advances the given sequence and returns its new value.

+		Volatile
nextval(sequence_name: regclass) → int

Advances the given sequence and returns its new value.

+		Volatile
setval(sequence_name: string, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: string, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
setval(sequence_name: regclass, value: int) → int

Set the given sequence’s current value. The next call to nextval will return value + Increment

+		Volatile
setval(sequence_name: regclass, value: int, is_called: bool) → int

Set the given sequence’s current value. If is_called is false, the next call to nextval will return value; otherwise value + Increment.

+		Volatile
+ +### Set-returning functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
aclexplode(aclitems: string[]) → tuple{oid AS grantor, oid AS grantee, string AS privilege_type, bool AS is_grantable}

Produces a virtual table containing aclitem privileges.

+		Stable
aclexplode(aclitems: aclitem[]) → tuple{oid AS grantor, oid AS grantee, string AS privilege_type, bool AS is_grantable}

Produces a virtual table containing aclitem privileges.

+		Stable
generate_series(start: int, end: int) → int

Produces a virtual table containing the integer values from start to end, inclusive.

+		Immutable
generate_series(start: int, end: int, step: int) → int

Produces a virtual table containing the integer values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamp, end: timestamp, step: interval) → timestamp

Produces a virtual table containing the timestamp values from start to end, inclusive, by increment of step.

+		Immutable
generate_series(start: timestamptz, end: timestamptz, step: interval) → timestamptz

Produces a virtual table containing the timestampTZ values from start to end, inclusive, by increment of step.

+		Immutable
generate_subscripts(array: anyelement[]) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int) → int

Returns a series comprising the given array’s subscripts.

+		Immutable
generate_subscripts(array: anyelement[], dim: int, reverse: bool) → int

Returns a series comprising the given array’s subscripts.

+

When reverse is true, the series is returned in reverse order.

+		Immutable
information_schema._pg_expandarray(input: anyelement[]) → tuple{anyelement AS x, int AS n}

Returns the input array as a set of rows with an index

+		Immutable
json_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
json_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
json_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
jsonb_object_keys(input: jsonb) → string

Returns sorted set of keys in the outermost JSON object.

+		Immutable
jsonb_to_record(input: jsonb) → tuple

Builds an arbitrary record from a JSON object.

+		Stable
jsonb_to_recordset(input: jsonb) → tuple

Builds an arbitrary set of records from a JSON array of objects.

+		Stable
pg_get_keywords() → tuple{string AS word, string AS catcode, string AS catdesc}

Produces a virtual table containing the keywords known to the SQL parser.

+		Immutable
pg_options_to_table(options: string[]) → tuple{string AS option_name, string AS option_value}

Converts the options array format to a table.

+		Stable
regexp_split_to_table(string: string, pattern: string) → string

Split string using a POSIX regular expression as the delimiter.

+		Immutable
regexp_split_to_table(string: string, pattern: string, flags: string) → string

Split string using a POSIX regular expression as the delimiter with flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
unnest(anyelement[], anyelement[], anyelement[]...) → tuple{anyelement AS unnest, anyelement AS unnest, anyelement AS unnest}

Returns the input arrays as a set of rows

+		Immutable
unnest(input: anyelement[]) → anyelement

Returns the input array as a set of rows

+		Immutable
workload_index_recs() → tuple{string AS index_rec, bytes[] AS fingerprint_ids}

Returns index recommendations and the fingerprint ids that the indexes will impact

+		Immutable
workload_index_recs(timestamptz: timestamptz) → tuple{string AS index_rec, bytes[] AS fingerprint_ids}

Returns index recommendations and the fingerprint ids that the indexes will impact

+		Immutable
+ +### Spatial functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
_st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
_st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant does not utilize any spatial index.

+		Immutable
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(catalog_name: string, schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(schema_name: string, table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
addgeometrycolumn(table_name: string, column_name: string, srid: int, type: string, dimension: int, use_typmod: bool) → string

Adds a new geometry column to an existing table and returns metadata about the column created.

+		Volatile
geometrytype(geometry: geometry) → string

Returns the type of geometry as a string.

+

This function utilizes the GEOS module.

+		Immutable
geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
postgis_addbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_dropbbox(geometry: geometry) → geometry

Compatibility placeholder function with PostGIS. This does not perform any operation on the Geometry.

+		Immutable
postgis_extensions_upgrade() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_full_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_geos_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_getbbox(geometry: geometry) → box2d

Returns a box2d encapsulating the given Geometry.

+		Immutable
postgis_hasbbox(geometry: geometry) → bool

Returns whether a given Geometry has a bounding box. False for points and empty geometries; always true otherwise.

+		Immutable
postgis_lib_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_lib_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_liblwgeom_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_libxml_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_proj_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_build_date() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_installed() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_scripts_released() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
postgis_wagyu_version() → string

Compatibility placeholder function with PostGIS. Returns a fixed string based on PostGIS 3.0.1, with minor edits.

+		Immutable
st_3dlength(geometry: geometry) → float

Returns the 3-dimensional or 2-dimensional length of the geometry.

+

Note ST_3DLength is only valid for LineString or MultiLineString. +For 2-D lines it will return the 2-D length (same as ST_Length and ST_Length2D)

+

This function utilizes the GEOS module.

+		Immutable
st_addmeasure(geometry: geometry, start: float, end: float) → geometry

Returns a copy of a LineString or MultiLineString with measure coordinates linearly interpolated between the specified start and end values. Any existing M coordinates will be overwritten.

+		Immutable
st_addpoint(line_string: geometry, point: geometry) → geometry

Adds a Point to the end of a LineString.

+		Immutable
st_addpoint(line_string: geometry, point: geometry, index: int) → geometry

Adds a Point to a LineString at the given 0-based index (-1 to append).

+		Immutable
st_affine(geometry: geometry, a: float, b: float, c: float, d: float, e: float, f: float, g: float, h: float, i: float, x_off: float, y_off: float, z_off: float) → geometry

Applies a 3D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b c x_off \ / x
+| d e f y_off | | y | +| g h i z_off | | z | +\ 0 0 0 1 / \ 0 /

+		Immutable
st_affine(geometry: geometry, a: float, b: float, d: float, e: float, x_off: float, y_off: float) → geometry

Applies a 2D affine transformation to the given geometry.

+

The matrix transformation will be applied as follows for each coordinate: +/ a b x_off \ / x
+| d e y_off | | y | +\ 0 0 1 / \ 0 /

+		Immutable
st_angle(line1: geometry, line2: geometry) → float

Returns the clockwise angle between two LINESTRING geometries, treating them as vectors between their start- and endpoints. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry) → float

Returns the clockwise angle between the vectors formed by point2,point1 and point2,point3. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_angle(point1: geometry, point2: geometry, point3: geometry, point4: geometry) → float

Returns the clockwise angle between the vectors formed by point1,point2 and point3,point4. The arguments must be POINT geometries. Returns NULL if any vectors have 0 length.

+		Immutable
st_area(geography: geography) → float

Returns the area of the given geography in meters^2. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geography: geography, use_spheroid: bool) → float

Returns the area of the given geography in meters^2.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_area(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_area(geometry_str: string) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_area2d(geometry: geometry) → float

Returns the area of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_asbinary(geography: geography) → bytes

Returns the WKB representation of a given Geography.

+		Immutable
st_asbinary(geography: geography, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asbinary(geometry: geometry) → bytes

Returns the WKB representation of a given Geometry.

+		Immutable
st_asbinary(geometry: geometry, xdr_or_ndr: string) → bytes

Returns the WKB representation of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_asencodedpolyline(geometry: geometry) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Preserves 5 decimal places.

+		Immutable
st_asencodedpolyline(geometry: geometry, precision: int4) → string

Returns the geometry as an Encoded Polyline. +This format is used by Google Maps with precision=5 and by Open Source Routing Machine with precision=5 and 6. +Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+		Immutable
st_asewkb(geography: geography) → bytes

Returns the EWKB representation of a given Geography.

+		Immutable
st_asewkb(geometry: geometry) → bytes

Returns the EWKB representation of a given Geometry.

+		Immutable
st_asewkt(geography: geography) → string

Returns the EWKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_asewkt(geography: geography, max_decimal_digits: int) → string

Returns the EWKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry: geometry) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_asewkt(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_asewkt(geometry_str: string) → string

Returns the EWKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asewkt(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geography: geography) → string

Returns the GeoJSON representation of a given Geography. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geography: geography, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geography with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option (default for Geography)
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326
    • +
+		Immutable
st_asgeojson(geometry: geometry) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+		Immutable
st_asgeojson(geometry: geometry, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+		Immutable
st_asgeojson(geometry_str: string) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(geometry_str: string, max_decimal_digits: int, options: int) → string

Returns the GeoJSON representation of a given Geometry with max_decimal_digits output for each coordinate value.

+

Options is a flag that can be bitmasked. The options are:

+
    +
  • 0: no option
    • +
  • 1: GeoJSON BBOX
    • +
  • 2: GeoJSON Short CRS (e.g EPSG:4326)
    • +
  • 4: GeoJSON Long CRS (e.g urn:ogc:def:crs:EPSG::4326)
    • +
  • 8: GeoJSON Short CRS if not EPSG:4326 (default for Geometry)
    • +
+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asgeojson(row: tuple) → string

Returns the GeoJSON representation of a given Geometry. Coordinates have a maximum of 9 decimal digits.

+		Immutable
st_asgeojson(row: tuple, geo_column: string) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. Coordinates have a maximum of 9 decimal digits.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value.

+		Stable
st_asgeojson(row: tuple, geo_column: string, max_decimal_digits: int, pretty: bool) → string

Returns the GeoJSON representation of a given Geometry, using geo_column as the geometry for the given Feature. max_decimal_digits will be output for each coordinate value. Output will be pretty printed in JSON if pretty is true.

+		Stable
st_ashexewkb(geography: geography) → string

Returns the EWKB representation in hex of a given Geography.

+		Immutable
st_ashexewkb(geography: geography, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geography. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexewkb(geometry: geometry) → string

Returns the EWKB representation in hex of a given Geometry.

+		Immutable
st_ashexewkb(geometry: geometry, xdr_or_ndr: string) → string

Returns the EWKB representation in hex of a given Geometry. This variant has a second argument denoting the encoding - xdr for big endian and ndr for little endian.

+		Immutable
st_ashexwkb(geography: geography) → string

Returns the WKB representation in hex of a given Geography.

+		Immutable
st_ashexwkb(geometry: geometry) → string

Returns the WKB representation in hex of a given Geometry.

+		Immutable
st_askml(geography: geography) → string

Returns the KML representation of a given Geography.

+		Immutable
st_askml(geometry: geometry) → string

Returns the KML representation of a given Geometry.

+		Immutable
st_askml(geometry_str: string) → string

Returns the KML representation of a given Geometry.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping. +Uses 4096 as the tile extent size in tile coordinate space.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds. +Uses 256 as the buffer size in tile coordinate space for geometry clipping.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry will be clipped can be transformed.

+		Immutable
st_asmvtgeom(geometry: geometry, bbox: box2d, extent: int, buffer: int, clip: bool) → geometry

Transforms a geometry into the coordinate space of a MVT (Mapbox Vector Tile) tile, clipping it to the tile bounds if required.

+

The geometry must be in the coordinate system of the target map. +The function attempts to preserve geometry validity, and corrects it if needed. This may cause the result geometry to collapse to a lower dimension. +The rectangular bounds of the tile in the target map coordinate space must be provided, so the geometry can be transformed, and clipped if required.

+		Immutable
st_astext(geography: geography) → string

Returns the WKT representation of a given Geography. A default of 15 decimal digits is used.

+		Immutable
st_astext(geography: geography, max_decimal_digits: int) → string

Returns the WKT representation of a given Geography. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry: geometry) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+		Immutable
st_astext(geometry: geometry, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+		Immutable
st_astext(geometry_str: string) → string

Returns the WKT representation of a given Geometry. A maximum of 15 decimal digits is used.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astext(geometry_str: string, max_decimal_digits: int) → string

Returns the WKT representation of a given Geometry. The max_decimal_digits parameter controls the maximum decimal digits to print after the .. Use -1 to print as many digits as required to rebuild the same number.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_astwkb(geometry: geometry, precision_xy: int, precision_z: int, precision_m: int) → bytes

Returns the TWKB representation of a given geometry.

+		Immutable
st_azimuth(geography_a: geography, geography_b: geography) → float

Returns the azimuth in radians of the segment defined by the given point geographies, or NULL if the two points are coincident. It is solved using the Inverse geodesic problem.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_azimuth(geometry_a: geometry, geometry_b: geometry) → float

Returns the azimuth in radians of the segment defined by the given point geometries, or NULL if the two points are coincident.

+

The azimuth is angle is referenced from north, and is positive clockwise: North = 0; East = π/2; South = π; West = 3π/2.

+		Immutable
st_bdpolyfromtext(str: string, srid: int) → geometry

Returns a Polygon from multilinestring WKT with a SRID. If the input is not a multilinestring an error will be thrown.

+		Immutable
st_boundary(geometry: geometry) → geometry

Returns the closure of the combinatorial boundary of this Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_box2dfromgeohash(geohash: string) → box2d

Return a Box2D from a GeoHash string with max precision.

+		Immutable
st_box2dfromgeohash(geohash: string, precision: int) → box2d

Return a Box2D from a GeoHash string with supplied precision.

+		Immutable
st_buffer(geography: geography, distance: float) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, buffer_style_params: string) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geography: geography, distance: float, quad_segs: int) → geography

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+		Immutable
st_buffer(geometry: geometry, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry: geometry, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_buffer(geometry_str: string, distance: decimal) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, buffer_style_params: string) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant takes in a space separate parameter string, which will augment the buffer styles. Valid parameters are:

+
    +
  • quad_segs=<int>, default 8
    • +
  • endcap=<round|flat|butt|square>, default round
    • +
  • join=<round|mitre|miter|bevel>, default round
    • +
  • side=<both|left|right>, default both
    • +
  • mitre_limit=<float>, default 5.0
    • +
+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: float, quad_segs: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance from the +given Geometry.

+

This variant approximates the circle into quad_seg segments per line (the default is 8).

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_buffer(geometry_str: string, distance: int) → geometry

Returns a Geometry that represents all points whose distance is less than or equal to the given distance +from the given Geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_centroid(geography: geography) → geography

Returns the centroid of given geography. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geography: geography, use_spheroid: bool) → geography

Returns the centroid of given geography.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_centroid(geometry: geometry) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_centroid(geometry_str: string) → geometry

Returns the centroid of the given geometry.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_clipbybox2d(geometry: geometry, box2d: box2d) → geometry

Clips the geometry to conform to the bounding box specified by box2d.

+		Immutable
st_closestpoint(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the 2-dimensional point on geometry_a that is closest to geometry_b. This is the first point of the shortest line.

+		Immutable
st_collectionextract(geometry: geometry, type: int) → geometry

Given a collection, returns a multitype consisting only of elements of the specified type. If there are no elements of the given type, an EMPTY geometry is returned. Types are specified as 1=POINT, 2=LINESTRING, 3=POLYGON - other types are not supported.

+		Immutable
st_collectionhomogenize(geometry: geometry) → geometry

Returns the “simplest” representation of a collection’s contents. Collections of a single type will be returned as an appopriate multitype, or a singleton if it only contains a single geometry.

+		Immutable
st_combinebbox(box2d: box2d, geometry: geometry) → box2d

Combines the current bounding box with the bounding box of the Geometry.

+		Immutable
st_contains(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no points of geometry_b lie in the exterior of geometry_a, and there is at least one point in the interior of geometry_b that lies in the interior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_containsproperly(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_b intersects the interior of geometry_a but not the boundary or exterior of geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_convexhull(geometry: geometry) → geometry

Returns a geometry that represents the Convex Hull of the given geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_coorddim(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_coveredby(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_a is outside geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_coveredby(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_a is outside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_covers(geography_a: geography, geography_b: geography) → bool

Returns true if no point in geography_b is outside geography_a.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_covers(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if no point in geometry_b is outside geometry_a.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_crosses(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a has some - but not all - interior points in common with geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, inclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than or equal to distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dfullywithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if every pair of points comprising geometry_a and geometry_b are within distance units, exclusive. In other words, the ST_MaxDistance between geometry_a and geometry_b is less than distance units.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_difference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the difference of two Geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_dimension(geometry: geometry) → int

Returns the number of topological dimensions of a given Geometry.

+		Immutable
st_disjoint(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a does not overlap, touch or is within geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_distance(geography_a: geography, geography_b: geography) → float

Returns the distance in meters between geography_a and geography_b. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geography_a: geography, geography_b: geography, use_spheroid: bool) → float

Returns the distance in meters between geography_a and geography_b.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_distance(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance between the given geometries.

+		Immutable
st_distance(geometry_a_str: string, geometry_b_str: string) → float

Returns the distance between the given geometries.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_distancesphere(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_distancespheroid(geometry_a: geometry, geometry_b: geometry) → float

Returns the distance in meters between geometry_a and geometry_b assuming the coordinates represent lng/lat points on a spheroid.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, inclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithin(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, inclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive. Uses a spheroid to perform the operation.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geography_a: geography, geography_b: geography, distance: float, use_spheroid: bool) → bool

Returns true if any of geography_a is within distance meters of geography_b, exclusive.

+

When operating on a spheroid, this function will use the sphere to calculate the closest two points. The spheroid distance between these two points is calculated using GeographicLib. This follows observed PostGIS behavior.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a: geometry, geometry_b: geometry, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_dwithinexclusive(geometry_a_str: string, geometry_b_str: string, distance: float) → bool

Returns true if any of geometry_a is within distance units of geometry_b, exclusive.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_endpoint(geometry: geometry) → geometry

Returns the last point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_envelope(box2d: box2d) → geometry

Returns a bounding geometry for the given box.

+		Immutable
st_envelope(geometry: geometry) → geometry

Returns a bounding envelope for the given geometry.

+

For geometries which have a POINT or LINESTRING bounding box (i.e. is a single point +or a horizontal or vertical line), a POINT or LINESTRING is returned. Otherwise, the +returned POLYGON will be ordered Bottom Left, Top Left, Top Right, Bottom Right, +Bottom Left.

+		Immutable
st_equals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is spatially equal to geometry_b, i.e. ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = true.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_estimatedextent(schema_name: string, table_name: string, geocolumn_name: string, parent_only: bool) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+

The parent_only boolean is always ignored.

+		Stable
st_estimatedextent(table_name: string, geocolumn_name: string) → box2d

Returns the estimated extent of the geometries in the column of the given table. This currently always returns NULL.

+		Stable
st_expand(box2d: box2d, delta: float) → box2d

Extends the box2d by delta units across all dimensions.

+		Immutable
st_expand(box2d: box2d, delta_x: float, delta_y: float) → box2d

Extends the box2d by delta_x units in the x dimension and delta_y units in the y dimension.

+		Immutable
st_expand(geometry: geometry, delta: float) → geometry

Extends the bounding box represented by the geometry by delta units across all dimensions, returning a Polygon representing the new bounding box.

+		Immutable
st_expand(geometry: geometry, delta_x: float, delta_y: float) → geometry

Extends the bounding box represented by the geometry by delta_x units in the x dimension and delta_y units in the y dimension, returning a Polygon representing the new bounding box.

+		Immutable
st_exteriorring(geometry: geometry) → geometry

Returns the exterior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon.

+		Immutable
st_flipcoordinates(geometry: geometry) → geometry

Returns a new geometry with the X and Y axes flipped.

+		Immutable
st_force2d(geometry: geometry) → geometry

Returns a Geometry that is forced into XY layout with any Z or M dimensions discarded.

+		Immutable
st_force3d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to 0. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dm(geometry: geometry, defaultM: float) → geometry

Returns a Geometry that is forced into XYM layout. If a M coordinate doesn’t exist, it will be set to the specified default M value. If a Z coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate is present, it will be discarded.

+		Immutable
st_force3dz(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate is present, it will be discarded.

+		Immutable
st_force4d(geometry: geometry) → geometry

Returns a Geometry that is forced into XYZM layout. If a Z coordinate doesn’t exist, it will be set to 0. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified default Z value. If a M coordinate doesn’t exist, it will be set to 0.

+		Immutable
st_force4d(geometry: geometry, defaultZ: float, defaultM: float) → geometry

Returns a Geometry that is forced into XYZ layout. If a Z coordinate doesn’t exist, it will be set to the specified Z value. If a M coordinate doesn’t exist, it will be set to the specified M value.

+		Immutable
st_forcecollection(geometry: geometry) → geometry

Converts the geometry into a GeometryCollection.

+		Immutable
st_forcepolygonccw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_forcepolygoncw(geometry: geometry) → geometry

Returns a Geometry where all Polygon objects have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are unchanged.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Frechet distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_frechetdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Frechet distance between the given geometries, with the given segment densification (range 0.0-1.0, -1 to disable).

+

Smaller densify_frac gives a more accurate Fréchet distance. However, the computation time and memory usage increases with the square of the number of subsegments.

+

This function utilizes the GEOS module.

+		Immutable
st_generatepoints(geometry: geometry, npoints: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. Uses system time as a seed. +The requested number of points must be not larger than 65336.

+		Volatile
st_generatepoints(geometry: geometry, npoints: int4, seed: int4) → geometry

Generates pseudo-random points until the requested number are found within the input area. +The requested number of points must be not larger than 65336.

+		Immutable
st_geogfromewkb(val: bytes) → geography

Returns the Geography from an EWKB representation.

+		Immutable
st_geogfromewkt(val: string) → geography

Returns the Geography from an EWKT representation.

+		Immutable
st_geogfromgeojson(val: string) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromgeojson(val: jsonb) → geography

Returns the Geography from an GeoJSON representation.

+		Immutable
st_geogfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geogfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geogfromwkb(bytes: bytes, srid: int) → geography

Returns the Geography from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geogfromwkb(val: bytes) → geography

Returns the Geography from a WKB (or EWKB) representation.

+		Immutable
st_geographyfromtext(str: string, srid: int) → geography

Returns the Geography from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geographyfromtext(val: string) → geography

Returns the Geography from a WKT or EWKT representation.

+		Immutable
st_geohash(geography: geography) → string

Returns a GeoHash representation of the geeographywith full precision if a point is provided, or with variable precision based on the size of the feature.

+		Immutable
st_geohash(geography: geography, precision: int) → string

Returns a GeoHash representation of the geography with the supplied precision.

+		Immutable
st_geohash(geometry: geometry) → string

Returns a GeoHash representation of the geometry with full precision if a point is provided, or with variable precision based on the size of the feature. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geohash(geometry: geometry, precision: int) → string

Returns a GeoHash representation of the geometry with the supplied precision. This will error any coordinates are outside the bounds of longitude/latitude.

+		Immutable
st_geomcollfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomcollfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geomcollfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not GeometryCollection, NULL is returned.

+		Immutable
st_geometryfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geometryfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geometryn(geometry: geometry, n: int) → geometry

Returns the n-th Geometry (1-indexed). Returns NULL if out of bounds.

+		Immutable
st_geometrytype(geometry: geometry) → string

Returns the type of geometry as a string prefixed with ST_.

+

This function utilizes the GEOS module.

+		Immutable
st_geomfromewkb(val: bytes) → geometry

Returns the Geometry from an EWKB representation.

+		Immutable
st_geomfromewkt(val: string) → geometry

Returns the Geometry from an EWKT representation.

+		Immutable
st_geomfromgeohash(geohash: string) → geometry

Return a POLYGON Geometry from a GeoHash string with max precision.

+		Immutable
st_geomfromgeohash(geohash: string, precision: int) → geometry

Return a POLYGON Geometry from a GeoHash string with supplied precision.

+		Immutable
st_geomfromgeojson(val: string) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromgeojson(val: jsonb) → geometry

Returns the Geometry from an GeoJSON representation.

+		Immutable
st_geomfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_geomfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_geomfromwkb(bytes: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with the given SRID set.

+		Immutable
st_geomfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_hasarc(geometry: geometry) → bool

Returns whether there is a CIRCULARSTRING in the geometry.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the Hausdorff distance between the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_hausdorffdistance(geometry_a: geometry, geometry_b: geometry, densify_frac: float) → float

Returns the Hausdorff distance between the given geometries, with the given segment densification (range 0.0-1.0).

+

This function utilizes the GEOS module.

+		Immutable
st_interiorringn(geometry: geometry, n: int) → geometry

Returns the n-th (1-indexed) interior ring of a Polygon as a LineString. Returns NULL if the shape is not a Polygon, or the ring does not exist.

+		Immutable
st_intersection(geography_a: geography, geography_b: geography) → geography

Returns the point intersections of the given geographies.

+

This operation is done by transforming the object into a Geometry. This occurs by translating +the Geography objects into Geometry objects before applying an LAEA, UTM or Web Mercator +based projection based on the bounding boxes of the given Geography objects. When the result is +calculated, the result is transformed back into a Geography with SRID 4326.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_intersection(geometry_a_str: string, geometry_b_str: string) → geometry

Returns the point intersections of the given geometries.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_intersects(geography_a: geography, geography_b: geography) → bool

Returns true if geography_a shares any portion of space with geography_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the S2 library for spherical calculations.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_intersects(geometry_a_str: string, geometry_b_str: string) → bool

Returns true if geometry_a shares any portion of space with geometry_b.

+

The calculations performed are have a precision of 1cm.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_isclosed(geometry: geometry) → bool

Returns whether the geometry is closed as defined by whether the start and end points are coincident. Points are considered closed, empty geometries are not. For collections and multi-types, all members must be closed, as must all polygon rings.

+		Immutable
st_iscollection(geometry: geometry) → bool

Returns whether the geometry is of a collection type (including multi-types).

+		Immutable
st_isempty(geometry: geometry) → bool

Returns whether the geometry is empty.

+		Immutable
st_ispolygonccw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the counter-clockwise orientation and interior rings in the clockwise orientation. Non-Polygon objects are considered counter-clockwise.

+		Immutable
st_ispolygoncw(geometry: geometry) → bool

Returns whether the Polygon objects inside the Geometry have exterior rings in the clockwise orientation and interior rings in the counter-clockwise orientation. Non-Polygon objects are considered clockwise.

+		Immutable
st_isring(geometry: geometry) → bool

Returns whether the geometry is a single linestring that is closed and simple, as defined by ST_IsClosed and ST_IsSimple.

+

This function utilizes the GEOS module.

+		Immutable
st_issimple(geometry: geometry) → bool

Returns true if the geometry has no anomalous geometric points, e.g. that it intersects with or lies tangent to itself.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry) → bool

Returns whether the geometry is valid as defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalid(geometry: geometry, flags: int) → bool

Returns whether the geometry is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry) → string

Returns a string containing the reason the geometry is invalid along with the point of interest, or “Valid Geometry” if it is valid. Validity is defined by the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidreason(geometry: geometry, flags: int) → string

Returns the reason the geometry is invalid or “Valid Geometry” if it is valid.

+

For flags=0, validity is defined by the OGC spec.

+

For flags=1, validity considers self-intersecting rings forming holes as valid as per ESRI. This is not valid under OGC and CRDB spatial operations may not operate correctly.

+

This function utilizes the GEOS module.

+		Immutable
st_isvalidtrajectory(geometry: geometry) → bool

Returns whether the geometry encodes a valid trajectory.

+

Note the geometry must be a LineString with M coordinates.

+		Immutable
st_length(geography: geography) → float

Returns the length of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geography: geography, use_spheroid: bool) → float

Returns the length of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_length(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_length(geometry_str: string) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+

This variant will cast all geometry_str arguments into Geometry types.

+		Immutable
st_length2d(geometry: geometry) → float

Returns the length of the given geometry.

+

Note ST_Length is only valid for LineString - use ST_Perimeter for Polygon.

+

This function utilizes the GEOS module.

+		Immutable
st_linecrossingdirection(linestring_a: geometry, linestring_b: geometry) → int

Returns an interger value defining behavior of crossing of lines: +0: lines do not cross, +-1: linestring_b crosses linestring_a from right to left, +1: linestring_b crosses linestring_a from left to right, +-2: linestring_b crosses linestring_a multiple times from right to left, +2: linestring_b crosses linestring_a multiple times from left to right, +-3: linestring_b crosses linestring_a multiple times from left to left, +3: linestring_b crosses linestring_a multiple times from right to right.

+

Note that the top vertex of the segment touching another line does not count as a crossing, but the bottom vertex of segment touching another line is considered a crossing.

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string) → geometry

Creates a LineString from an Encoded Polyline string.

+

Returns valid results only if the polyline was encoded with 5 decimal places.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefromencodedpolyline(encoded_polyline: string, precision: int4) → geometry

Creates a LineString from an Encoded Polyline string.

+

Precision specifies how many decimal places will be preserved in Encoded Polyline. Value should be the same on encoding and decoding, or coordinates will be incorrect.

+

See http://developers.google.com/maps/documentation/utilities/polylinealgorithm

+		Immutable
st_linefrommultipoint(geometry: geometry) → geometry

Creates a LineString from a MultiPoint geometry.

+		Immutable
st_linefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_lineinterpolatepoint(geometry: geometry, fraction: float) → geometry

Returns a point along the given LineString which is at given fraction of LineString’s total length.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_lineinterpolatepoints(geometry: geometry, fraction: float, repeat: bool) → geometry

Returns one or more points along the LineString which is at an integral multiples of given fraction of LineString’s total length. If repeat is false (default true) then it returns first point.

+

Note If the result has zero or one points, it will be returned as a POINT. If it has two or more points, it will be returned as a MULTIPOINT.

+

This function utilizes the GEOS module.

+		Immutable
st_linelocatepoint(line: geometry, point: geometry) → float

Returns a float between 0 and 1 representing the location of the closest point on LineString to the given Point, as a fraction of total 2d line length.

+		Immutable
st_linemerge(geometry: geometry) → geometry

Returns a LineString or MultiLineString by joining together constituents of a MultiLineString with matching endpoints. If the input is not a MultiLineString or LineString, an empty GeometryCollection is returned.

+

This function utilizes the GEOS module.

+		Immutable
st_linestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not LineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_linestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not LineString, NULL is returned.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: decimal, end_fraction: decimal) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_linesubstring(linestring: geometry, start_fraction: float, end_fraction: float) → geometry

Return a linestring being a substring of the input one starting and ending at the given fractions of total 2D length. Second and third arguments are float8 values between 0 and 1.

+		Immutable
st_longestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the max distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the maximum distance between the geometry’s vertexes. The function will return the longest line that was discovered first when comparing maximum distances if more than one is found.

+		Immutable
st_m(geometry: geometry) → float

Returns the M coordinate of a geometry if it is a Point.

+		Immutable
st_makebox2d(geometry_a: geometry, geometry_b: geometry) → box2d

Creates a box2d from two points. Errors if arguments are not two non-empty points.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with SRID 0.

+		Immutable
st_makeenvelope(xmin: float, ymin: float, xmax: float, ymax: float, srid: int) → geometry

Creates a rectangular Polygon from the minimum and maximum values for X and Y with the given SRID.

+		Immutable
st_makepoint(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float) → geometry

Returns a new Point with the given X, Y, and Z coordinates.

+		Immutable
st_makepoint(x: float, y: float, z: float, m: float) → geometry

Returns a new Point with the given X, Y, Z, and M coordinates.

+		Immutable
st_makepointm(x: float, y: float, m: float) → geometry

Returns a new Point with the given X, Y, and M coordinates.

+		Immutable
st_makepolygon(geometry: geometry) → geometry

Returns a new Polygon with the given outer LineString.

+		Immutable
st_makepolygon(outer: geometry, interior: anyelement[]) → geometry

Returns a new Polygon with the given outer LineString and interior (hole) LineString(s).

+		Immutable
st_makevalid(geometry: geometry) → geometry

Returns a valid form of the given geometry according to the OGC spec.

+

This function utilizes the GEOS module.

+		Immutable
st_maxdistance(geometry_a: geometry, geometry_b: geometry) → float

Returns the maximum distance across every pair of points comprising the given geometries. Note if the geometries are the same, it will return the maximum distance between the geometry’s vertexes.

+		Immutable
st_memsize(geometry: geometry) → int

Returns the amount of memory space (in bytes) the geometry takes.

+		Immutable
st_minimumboundingcircle(geometry: geometry) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingcircle(geometry: geometry, num_segs: int) → geometry

Returns the smallest circle polygon that can fully contain a geometry.

+		Immutable
st_minimumboundingradius(geometry: geometry) → tuple{geometry AS center, float AS radius}

Returns a record containing the center point and radius of the smallest circle that can fully contains the given geometry.

+		Immutable
st_minimumclearance(geometry: geometry) → float

Returns the minimum distance a vertex can move before producing an invalid geometry. Returns Infinity if no minimum clearance can be found (e.g. for a single point).

+		Immutable
st_minimumclearanceline(geometry: geometry) → geometry

Returns a LINESTRING spanning the minimum distance a vertex can move before producing an invalid geometry. If no minimum clearance can be found (e.g. for a single point), an empty LINESTRING is returned.

+		Immutable
st_mlinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mlinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mlinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_mpointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_mpolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_mpolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_mpolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multi(geometry: geometry) → geometry

Returns the geometry as a new multi-geometry, e.g converts a POINT to a MULTIPOINT. If the input is already a multitype or collection, it is returned as is.

+		Immutable
st_multilinefromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinefromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinefromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multilinestringfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multilinestringfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiLineString, NULL is returned.

+		Immutable
st_multipointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPoint, NULL is returned.

+		Immutable
st_multipolyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_multipolygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_multipolygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not MultiPolygon, NULL is returned.

+		Immutable
st_ndims(geometry: geometry) → int

Returns the number of coordinate dimensions of a given Geometry.

+		Immutable
st_node(geometry: geometry) → geometry

Adds a node on a geometry for each intersection. Resulting geometry is always a MultiLineString.

+		Immutable
st_normalize(geometry: geometry) → geometry

Returns the geometry in its normalized form.

+

This function utilizes the GEOS module.

+		Immutable
st_npoints(geometry: geometry) → int

Returns the number of points in a given Geometry. Works for any shape type.

+		Immutable
st_nrings(geometry: geometry) → int

Returns the number of rings in a Polygon Geometry. Returns 0 if the shape is not a Polygon.

+		Immutable
st_numgeometries(geometry: geometry) → int

Returns the number of shapes inside a given Geometry.

+		Immutable
st_numinteriorring(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numinteriorrings(geometry: geometry) → int

Returns the number of interior rings in a Polygon Geometry. Returns NULL if the shape is not a Polygon.

+		Immutable
st_numpoints(geometry: geometry) → int

Returns the number of points in a LineString. Returns NULL if the Geometry is not a LineString.

+		Immutable
st_orderingequals(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is exactly equal to geometry_b, having all coordinates in the same order, as well as the same type, SRID, bounding box, and so on.

+		Immutable
st_orientedenvelope(geometry: geometry) → geometry

Returns a minimum rotated rectangle enclosing a geometry. +Note that more than one minimum rotated rectangle may exist. +May return a Point or LineString in the case of degenerate inputs.

+		Immutable
st_overlaps(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a intersects but does not completely contain geometry_b, or vice versa. “Does not completely” implies ST_Within(geometry_a, geometry_b) = ST_Within(geometry_b, geometry_a) = false.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_perimeter(geography: geography) → float

Returns the perimeter of the given geography in meters. Uses a spheroid to perform the operation.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geography: geography, use_spheroid: bool) → float

Returns the perimeter of the given geography in meters.

+

This function utilizes the S2 library for spherical calculations.

+

This function utilizes the GeographicLib library for spheroid calculations.

+		Immutable
st_perimeter(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_perimeter2d(geometry: geometry) → float

Returns the perimeter of the given geometry.

+

Note ST_Perimeter is only valid for Polygon - use ST_Length for LineString.

+

This function utilizes the GEOS module.

+		Immutable
st_point(x: float, y: float) → geometry

Returns a new Point with the given X and Y coordinates.

+		Immutable
st_pointfromgeohash(geohash: string) → geometry

Return a POINT Geometry from a GeoHash string with max precision.

+		Immutable
st_pointfromgeohash(geohash: string, precision: int) → geometry

Return a POINT Geometry from a GeoHash string with supplied precision.

+		Immutable
st_pointfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Point, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_pointfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Point, NULL is returned.

+		Immutable
st_pointinsidecircle(geometry: geometry, x_coord: float, y_coord: float, radius: float) → bool

Returns the true if the geometry is a point and is inside the circle. Returns false otherwise.

+		Immutable
st_pointn(geometry: geometry, n: int) → geometry

Returns the n-th Point of a LineString (1-indexed). Returns NULL if out of bounds or not a LineString.

+		Immutable
st_pointonsurface(geometry: geometry) → geometry

Returns a point that intersects with the given Geometry.

+

This function utilizes the GEOS module.

+		Immutable
st_points(geometry: geometry) → geometry

Returns all coordinates in the given Geometry as a MultiPoint, including duplicates.

+		Immutable
st_polyfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polyfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polyfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygon(geometry: geometry, srid: int) → geometry

Returns a new Polygon from the given LineString and sets its SRID. It is equivalent to ST_MakePolygon with a single argument followed by ST_SetSRID.

+		Immutable
st_polygonfromtext(str: string, srid: int) → geometry

Returns the Geometry from a WKT or EWKT representation with an SRID. If the shape underneath is not Polygon, NULL is returned. If the SRID is present in both the EWKT and the argument, the argument value is used.

+		Immutable
st_polygonfromtext(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_polygonfromwkb(wkb: bytes, srid: int) → geometry

Returns the Geometry from a WKB (or EWKB) representation with an SRID. If the shape underneath is not Polygon, NULL is returned.

+		Immutable
st_project(geography: geography, distance: float, azimuth: float) → geography

Returns a point projected from a start point along a geodesic using a given distance and azimuth (bearing). +This is known as the direct geodesic problem.

+

The distance is given in meters. Negative values are supported.

+

The azimuth (also known as heading or bearing) is given in radians. It is measured clockwise from true north (azimuth zero). +East is azimuth π/2 (90 degrees); south is azimuth π (180 degrees); west is azimuth 3π/2 (270 degrees). +Negative azimuth values and values greater than 2π (360 degrees) are supported.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b.

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, bnr: int) → string

Returns the DE-9IM spatial relation between geometry_a and geometry_b using the given boundary node rule (1:OGC/MOD2, 2:Endpoint, 3:MultivalentEndpoint, 4:MonovalentEndpoint).

+

This function utilizes the GEOS module.

+		Immutable
st_relate(geometry_a: geometry, geometry_b: geometry, pattern: string) → bool

Returns whether the DE-9IM spatial relation between geometry_a and geometry_b matches the DE-9IM pattern.

+

This function utilizes the GEOS module.

+		Immutable
st_relatematch(intersection_matrix: string, pattern: string) → bool

Returns whether the given DE-9IM intersection matrix satisfies the given pattern.

+		Immutable
st_removepoint(line_string: geometry, index: int) → geometry

Removes the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_removerepeatedpoints(geometry: geometry) → geometry

Returns a geometry with repeated points removed.

+		Immutable
st_removerepeatedpoints(geometry: geometry, tolerance: float) → geometry

Returns a geometry with repeated points removed, within the given distance tolerance.

+		Immutable
st_reverse(geometry: geometry) → geometry

Returns a modified geometry by reversing the order of its vertices.

+		Immutable
st_rotate(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_point: geometry) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotate(g: geometry, angle_radians: float, origin_x: float, origin_y: float) → geometry

Returns a modified Geometry whose coordinates are rotated around the provided origin by a rotation angle.

+		Immutable
st_rotatex(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the x axis by a rotation angle.

+		Immutable
st_rotatey(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the y axis by a rotation angle.

+		Immutable
st_rotatez(g: geometry, angle_radians: float) → geometry

Returns a modified Geometry whose coordinates are rotated about the z axis by a rotation angle.

+		Immutable
st_s2covering(geography: geography) → geography

Returns a geography which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geography: geography, settings: string) → geography

Returns a geography which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geography, 's2_max_level=15,s2_level_mod=3').

+		Immutable
st_s2covering(geometry: geometry) → geometry

Returns a geometry which represents the S2 covering used by the index using the default index configuration.

+		Immutable
st_s2covering(geometry: geometry, settings: string) → geometry

Returns a geometry which represents the S2 covering used by the index using the index configuration specified by the settings parameter.

+

The settings parameter uses the same format as the parameters inside the WITH in CREATE INDEX ... WITH (...), e.g. CREATE INDEX t_idx ON t USING GIST(geom) WITH (s2_max_level=15, s2_level_mod=3) can be tried using SELECT ST_S2Covering(geometry, 's2_max_level=15,s2_level_mod=3')

+		Immutable
st_scale(g: geometry, factor: geometry) → geometry

Returns a modified Geometry scaled by taking in a Geometry as the factor.

+		Immutable
st_scale(g: geometry, factor: geometry, origin: geometry) → geometry

Returns a modified Geometry scaled by the Geometry factor relative to a false origin.

+		Immutable
st_scale(geometry: geometry, x_factor: float, y_factor: float) → geometry

Returns a modified Geometry scaled by the given factors.

+		Immutable
st_segmentize(geography: geography, max_segment_length_meters: float) → geography

Returns a modified Geography having no segment longer than the given max_segment_length meters.

+

The calculations are done on a sphere.

+

This function utilizes the S2 library for spherical calculations.

+		Immutable
st_segmentize(geometry: geometry, max_segment_length: float) → geometry

Returns a modified Geometry having no segment longer than the given max_segment_length. Length units are in units of spatial reference.

+		Immutable
st_setpoint(line_string: geometry, index: int, point: geometry) → geometry

Sets the Point at the given 0-based index and returns the modified LineString geometry.

+		Immutable
st_setsrid(geography: geography, srid: int) → geography

Sets a Geography to a new SRID without transforming the coordinates.

+		Immutable
st_setsrid(geometry: geometry, srid: int) → geometry

Sets a Geometry to a new SRID without transforming the coordinates.

+		Immutable
st_sharedpaths(geometry_a: geometry, geometry_b: geometry) → geometry

Returns a collection containing paths shared by the two input geometries.

+

Those going in the same direction are in the first element of the collection, +those going in the opposite direction are in the second element. +The paths themselves are given in the direction of the first geometry.

+		Immutable
st_shiftlongitude(geometry: geometry) → geometry

Returns a modified version of a geometry in which the longitude (X coordinate) of each point is incremented by 360 if it is <0 and decremented by 360 if it is >180. The result is only meaningful if the coordinates are in longitude/latitude.

+		Immutable
st_shortestline(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the LineString corresponds to the minimum distance across every pair of points comprising the given geometries.

+

Note if geometries are the same, it will return the LineString with the minimum distance between the geometry’s vertexes. The function will return the shortest line that was discovered first when comparing minimum distances if more than one is found.

+		Immutable
st_simplify(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm.

+

This function utilizes the GEOS module.

+		Immutable
st_simplify(geometry: geometry, tolerance: float, preserve_collapsed: bool) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, retaining objects that would be too small given the tolerance if preserve_collapsed is set to true.

+		Immutable
st_simplifypreservetopology(geometry: geometry, tolerance: float) → geometry

Simplifies the given geometry using the Douglas-Peucker algorithm, avoiding the creation of invalid geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_snap(input: geometry, target: geometry, tolerance: float) → geometry

Snaps the vertices and segments of input geometry the target geometry’s vertices. +Tolerance is used to control where snapping is performed. The result geometry is the input geometry with the vertices snapped. +If no snapping occurs then the input geometry is returned unchanged.

+		Immutable
st_snaptogrid(geometry: geometry, origin: geometry, size_x: float, size_y: float, size_z: float, size_m: float) → geometry

Snap a geometry to a grid defined by the given origin and X, Y, Z, and M cell sizes. Any dimension with a 0 cell size will not be snapped.

+		Immutable
st_snaptogrid(geometry: geometry, origin_x: float, origin_y: float, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y based on an origin of (origin_x, origin_y).

+		Immutable
st_snaptogrid(geometry: geometry, size: float) → geometry

Snap a geometry to a grid of the given size. The specified size is only used to snap X and Y coordinates.

+		Immutable
st_snaptogrid(geometry: geometry, size_x: float, size_y: float) → geometry

Snap a geometry to a grid of with X coordinates snapped to size_x and Y coordinates snapped to size_y.

+		Immutable
st_srid(geography: geography) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geography as defined in spatial_ref_sys table.

+		Immutable
st_srid(geometry: geometry) → int

Returns the Spatial Reference Identifier (SRID) for the ST_Geometry as defined in spatial_ref_sys table.

+		Immutable
st_startpoint(geometry: geometry) → geometry

Returns the first point of a geometry which has shape LineString. Returns NULL if the geometry is not a LineString.

+		Immutable
st_subdivide(geometry: geometry) → geometry

Returns a geometry divided into parts, where each part contains no more than 256 vertices.

+		Immutable
st_subdivide(geometry: geometry, max_vertices: int4) → geometry

Returns a geometry divided into parts, where each part contains no more than the number of vertices provided.

+		Immutable
st_summary(geography: geography) → string

Returns a text summary of the contents of the geography.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_summary(geometry: geometry) → string

Returns a text summary of the contents of the geometry.

+

Flags shown square brackets after the geometry type have the following meaning:

+
    +
  • M: has M coordinate
    • +
  • Z: has Z coordinate
    • +
  • B: has a cached bounding box
    • +
  • G: is geography
    • +
  • S: has spatial reference system
    • +
+		Immutable
st_swapordinates(geometry: geometry, swap_ordinate_string: string) → geometry

Returns a version of the given geometry with given ordinates swapped. +The swap_ordinate_string parameter is a 2-character string naming the ordinates to swap. Valid names are: x, y, z and m.

+		Immutable
st_symdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_symmetricdifference(geometry_a: geometry, geometry_b: geometry) → geometry

Returns the symmetric difference of both geometries.

+

This function utilizes the GEOS module.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4, bounds: geometry) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_tileenvelope(tileZoom: int4, tileX: int4, tileY: int4, bounds: geometry, margin: float) → geometry

Creates a rectangular Polygon giving the extent of a tile in the XYZ tile system. +The tile is specifed by the zoom level Z and the XY index of the tile in the grid at that level. +Can be used to define the tile bounds required by ST_AsMVTGeom to convert geometry into the MVT tile coordinate space.

+		Immutable
st_touches(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if the only points in common between geometry_a and geometry_b are on the boundary. Note points do not touch other points.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, srid: int) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates. The supplied SRID is set on the new geometry.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, from_proj_text: string, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system assuming the from_proj_text to the new to_proj_text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, srid: int) → geometry

Transforms a geometry into the given SRID coordinate reference system by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_transform(geometry: geometry, to_proj_text: string) → geometry

Transforms a geometry into the coordinate reference system referenced by the projection text by projecting its coordinates.

+

This function utilizes the PROJ library for coordinate projections.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_translate(g: geometry, delta_x: float, delta_y: float, delta_z: float) → geometry

Returns a modified Geometry translated by the given deltas.

+		Immutable
st_transscale(geometry: geometry, delta_x: float, delta_y: float, x_factor: float, y_factor: float) → geometry

Translates the geometry using the deltaX and deltaY args, then scales it using the XFactor, YFactor args, working in 2D only.

+		Immutable
st_unaryunion(geometry: geometry) → geometry

Returns a union of the components for any geometry or geometry collection provided. Dissolves boundaries of a multipolygon.

+		Immutable
st_voronoilines(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoilines(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry asthe boundaries between cells in that diagram as a MultiLineString.

+		Immutable
st_voronoipolygons(geometry: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_voronoipolygons(geometry: geometry, tolerance: float, extend_to: geometry) → geometry

Returns a two-dimensional Voronoi diagram from the vertices of the supplied geometry.

+		Immutable
st_within(geometry_a: geometry, geometry_b: geometry) → bool

Returns true if geometry_a is completely inside geometry_b.

+

This function utilizes the GEOS module.

+

This function variant will attempt to utilize any available spatial index.

+		Immutable
st_wkbtosql(val: bytes) → geometry

Returns the Geometry from a WKB (or EWKB) representation.

+		Immutable
st_wkttosql(val: string) → geometry

Returns the Geometry from a WKT or EWKT representation.

+		Immutable
st_x(geometry: geometry) → float

Returns the X coordinate of a geometry if it is a Point.

+		Immutable
st_xmax(box2d: box2d) → float

Returns the maximum X ordinate of a box2d.

+		Immutable
st_xmax(geometry: geometry) → float

Returns the maximum X ordinate of a geometry.

+		Immutable
st_xmin(box2d: box2d) → float

Returns the minimum X ordinate of a box2d.

+		Immutable
st_xmin(geometry: geometry) → float

Returns the minimum X ordinate of a geometry.

+		Immutable
st_y(geometry: geometry) → float

Returns the Y coordinate of a geometry if it is a Point.

+		Immutable
st_ymax(box2d: box2d) → float

Returns the maximum Y ordinate of a box2d.

+		Immutable
st_ymax(geometry: geometry) → float

Returns the maximum Y ordinate of a geometry.

+		Immutable
st_ymin(box2d: box2d) → float

Returns the minimum Y ordinate of a box2d.

+		Immutable
st_ymin(geometry: geometry) → float

Returns the minimum Y ordinate of a geometry.

+		Immutable
st_z(geometry: geometry) → float

Returns the Z coordinate of a geometry if it is a Point.

+		Immutable
st_zmflag(geometry: geometry) → int2

Returns a code based on the ZM coordinate dimension of a geometry (XY = 0, XYM = 1, XYZ = 2, XYZM = 3).

+		Immutable
+ +### String and byte functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
ascii(val: string) → int

Returns the character code of the first character in val. Despite the name, the function supports Unicode too.

+		Immutable
bit_count(val: bytes) → int

Calculates the number of bits set used to represent val.

+		Immutable
bit_count(val: varbit) → int

Calculates the number of bits set used to represent val.

+		Immutable
bit_length(val: bytes) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: string) → int

Calculates the number of bits used to represent val.

+		Immutable
bit_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
bitmask_and(a: string, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: string, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: string) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_and(a: varbit, b: varbit) → varbit

Calculates bitwise AND value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: string, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: string) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_or(a: varbit, b: varbit) → varbit

Calculates bitwise OR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: string, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: string) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
bitmask_xor(a: varbit, b: varbit) → varbit

Calculates bitwise XOR value of unsigned bit arrays ‘a’ and ‘b’ that may have different lengths.

+		Immutable
btrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning or end of input (applies recursively).

+

For example, btrim('doggie', 'eod') returns ggi.

+		Immutable
btrim(val: string) → string

Removes all spaces from the beginning and end of val.

+		Immutable
char_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
char_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
character_length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
character_length(val: string) → int

Calculates the number of characters in val.

+		Immutable
chr(val: int) → string

Returns the character with the code given in val. Inverse function of ascii().

+		Immutable
compress(data: bytes, codec: string) → bytes

Compress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
concat(any...) → string

Concatenates a comma-separated list of strings.

+		Immutable
concat_ws(string, any...) → string

Uses the first argument as a separator between the concatenation of the subsequent arguments.

+

For example concat_ws('!','wow','great') returns wow!great.

+		Immutable
convert_from(str: bytes, enc: string) → string

Decode the bytes in str into a string using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
convert_to(str: string, enc: string) → bytes

Encode the string str as a byte array using encoding enc. Supports encodings ‘UTF8’ and ‘LATIN1’.

+		Immutable
decode(text: string, format: string) → bytes

Decodes data using format (hex / escape / base64).

+		Immutable
decompress(data: bytes, codec: string) → bytes

Decompress data with the specified codec (gzip, ‘lz4’, ‘snappy’, 'zstd).

+		Immutable
difference(source: string, target: string) → int

Convert two strings to their Soundex codes and report the number of matching code positions.

+		Immutable
encode(data: bytes, format: string) → string

Encodes data using format (hex / escape / base64).

+		Immutable
format(string, any...) → string

Interprets the first argument as a format string similar to C sprintf and interpolates the remaining arguments.

+		Stable
from_ip(val: bytes) → string

Converts the byte string representation of an IP to its character string representation.

+		Immutable
from_uuid(val: bytes) → string

Converts the byte string representation of a UUID to its character string representation.

+		Immutable
get_bit(bit_string: varbit, index: int) → int

Extracts a bit at given index in the bit array.

+		Immutable
get_bit(byte_string: bytes, index: int) → int

Extracts a bit at the given index in the byte array.

+		Immutable
get_byte(byte_string: bytes, index: int) → int

Extracts a byte at the given index in the byte array.

+		Immutable
initcap(val: string) → string

Capitalizes the first letter of val.

+		Immutable
left(input: bytes, return_set: int) → bytes

Returns the first return_set bytes from input.

+		Immutable
left(input: string, return_set: int) → string

Returns the first return_set characters from input.

+		Immutable
length(val: bytes) → int

Calculates the number of bytes in val.

+		Immutable
length(val: string) → int

Calculates the number of characters in val.

+		Immutable
length(val: varbit) → int

Calculates the number of bits in val.

+		Immutable
lower(val: string) → string

Converts all characters in val to their lower-case equivalents.

+		Immutable
lpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the left of string.If string is longer than length it is truncated.

+		Immutable
lpad(string: string, length: int, fill: string) → string

Pads string by adding fill to the left of string to make it length. If string is longer than length it is truncated.

+		Immutable
ltrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the beginning (left-hand side) of input (applies recursively).

+

For example, ltrim('doggie', 'od') returns ggie.

+		Immutable
ltrim(val: string) → string

Removes all spaces from the beginning (left-hand side) of val.

+		Immutable
md5(bytes...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
md5(string...) → string

Calculates the MD5 hash value of a set of values.

+		Leakproof
octet_length(val: bytes) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: string) → int

Calculates the number of bytes used to represent val.

+		Immutable
octet_length(val: varbit) → int

Calculates the number of bits used to represent val.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int) → string

Replaces characters in input with overlay_val starting at start_pos (begins at 1).

+

For example, overlay('doggie', 'CAT', 2) returns dCATie.

+		Immutable
overlay(input: string, overlay_val: string, start_pos: int, end_pos: int) → string

Deletes the characters in input between start_pos and end_pos (count starts at 1), and then insert overlay_val at start_pos.

+		Immutable
parse_date(string: string, datestyle: string) → date

Parses a date assuming it is in format specified by DateStyle.

+		Immutable
parse_date(val: string) → date

Parses a date assuming it is in MDY format.

+		Immutable
parse_ident(qualified_identifier: string) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. Extra characters after the last identifier are considered an error

+		Immutable
parse_ident(qualified_identifier: string, strict: bool) → string[]

Splits qualified_identifier into an array of identifiers, removing any quoting of individual identifiers. If strict is false, then extra characters after the last identifier are ignored.

+		Immutable
parse_interval(string: string, style: string) → interval

Convert a string to an interval using the given IntervalStyle.

+		Immutable
parse_interval(val: string) → interval

Convert a string to an interval assuming the Postgres IntervalStyle.

+		Immutable
parse_time(string: string, timestyle: string) → time

Parses a time assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_time(val: string) → time

Parses a time assuming the date (if any) is in MDY format.

+		Immutable
parse_timestamp(string: string, datestyle: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates formatted using the given DateStyle.

+		Immutable
parse_timestamp(val: string) → timestamp

Convert a string containing an absolute timestamp to the corresponding timestamp assuming dates are in MDY format.

+		Immutable
parse_timetz(string: string, timestyle: string) → timetz

Parses a timetz assuming the date (if any) is in format specified by DateStyle.

+		Immutable
parse_timetz(val: string) → timetz

Parses a timetz assuming the date (if any) is in MDY format.

+		Immutable
prettify_statement(statement: string, line_width: int, align_mode: int, case_mode: int) → string

Prettifies a statement using a user-configured pretty-printing config. +Align mode values range from 0 - 3, representing no, partial, full, and extra alignment respectively. +Case mode values range between 0 - 1, representing lower casing and upper casing respectively.

+		Immutable
prettify_statement(val: string) → string

Prettifies a statement using a the default pretty-printing config.

+		Immutable
quote_ident(val: string) → string

Return val suitably quoted to serve as identifier in a SQL statement.

+		Immutable
quote_literal(val: string) → string

Return val suitably quoted to serve as string literal in a SQL statement.

+		Immutable
quote_literal(val: anyelement) → string

Coerce val to a string and then quote it as a literal.

+		Stable
quote_nullable(val: string) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Immutable
quote_nullable(val: anyelement) → string

Coerce val to a string and then quote it as a literal. If val is NULL, returns ‘NULL’.

+		Stable
regexp_extract(input: string, regex: string) → string

Returns the first match for the Regular Expression regex in input.

+		Immutable
regexp_replace(input: string, regex: string, replace: string) → string

Replaces matches for the Regular Expression regex in input with the Regular Expression replace.

+		Immutable
regexp_replace(input: string, regex: string, replace: string, flags: string) → string

Replaces matches for the regular expression regex in input with the regular expression replace using flags.

+

CockroachDB supports the following flags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagDescription
cCase-sensitive matching
gGlobal matching (match each substring instead of only the first)
iCase-insensitive matching
m or nNewline-sensitive (see below)
pPartial newline-sensitive matching (see below)
sNewline-insensitive (default)
wInverse partial newline-sensitive matching (see below)
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Mode. and [^...] match newlines^ and $ match line boundaries
syesno
wyesyes
pnono
m/nnoyes
+		Immutable
repeat(input: string, repeat_counter: int) → string

Concatenates input repeat_counter number of times.

+

For example, repeat('dog', 2) returns dogdog.

+		Immutable
replace(input: string, find: string, replace: string) → string

Replaces all occurrences of find with replace in input

+		Immutable
reverse(val: string) → string

Reverses the order of the string’s characters.

+		Immutable
right(input: bytes, return_set: int) → bytes

Returns the last return_set bytes from input.

+		Immutable
right(input: string, return_set: int) → string

Returns the last return_set characters from input.

+		Immutable
rpad(string: string, length: int) → string

Pads string to length by adding ’ ’ to the right of string. If string is longer than length it is truncated.

+		Immutable
rpad(string: string, length: int, fill: string) → string

Pads string to length by adding fill to the right of string. If string is longer than length it is truncated.

+		Immutable
rtrim(input: string, trim_chars: string) → string

Removes any characters included in trim_chars from the end (right-hand side) of input (applies recursively).

+

For example, rtrim('doggie', 'ei') returns dogg.

+		Immutable
rtrim(val: string) → string

Removes all spaces from the end (right-hand side) of val.

+		Immutable
set_bit(bit_string: varbit, index: int, to_set: int) → varbit

Updates a bit at given index in the bit array.

+		Immutable
set_bit(byte_string: bytes, index: int, to_set: int) → bytes

Updates a bit at the given index in the byte array.

+		Immutable
set_byte(byte_string: bytes, index: int, to_set: int) → bytes

Updates a byte at the given index in the byte array.

+		Immutable
sha1(bytes...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha1(string...) → string

Calculates the SHA1 hash value of a set of values.

+		Leakproof
sha224(bytes...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha224(string...) → string

Calculates the SHA224 hash value of a set of values.

+		Leakproof
sha256(bytes...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha256(string...) → string

Calculates the SHA256 hash value of a set of values.

+		Leakproof
sha384(bytes...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha384(string...) → string

Calculates the SHA384 hash value of a set of values.

+		Leakproof
sha512(bytes...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
sha512(string...) → string

Calculates the SHA512 hash value of a set of values.

+		Leakproof
similar_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(pattern: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern.

+		Immutable
similar_to_escape(pattern: string, escape: string) → string

Converts a SQL regexp pattern to a POSIX regexp pattern using escape as an escape token.

+		Immutable
similar_to_escape(unescaped: string, pattern: string, escape: string) → bool

Matches unescaped with pattern using escape as an escape token.

+		Immutable
split_part(input: string, delimiter: string, return_index_pos: int) → string

Splits input using delimiter and returns the field at return_index_pos (starting from 1). If return_index_pos is negative, it returns the |return_index_pos|'th field from the end.

+

For example, split_part('123.456.789.0', '.', 3) returns 789.

+		Immutable
strpos(input: bytes, find: bytes) → int

Calculates the position where the byte subarray find begins in input.

+		Immutable
strpos(input: string, find: string) → int

Calculates the position where the string find begins in input.

+

For example, strpos('doggie', 'gie') returns 4.

+		Immutable
strpos(input: varbit, find: varbit) → int

Calculates the position where the bit subarray find begins in input.

+		Immutable
substr(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substr(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substr(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substr(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substr(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: bytes, start_pos: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: bytes, start_pos: int, length: int) → bytes

Returns a byte subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: string, regex: string) → string

Returns a substring of input that matches the regular expression regex.

+		Immutable
substring(input: string, regex: string, escape_char: string) → string

Returns a substring of input that matches the regular expression regex using escape_char as your escape character instead of \.

+		Immutable
substring(input: string, start_pos: int) → string

Returns a substring of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: string, start_pos: int, length: int) → string

Returns a substring of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring(input: varbit, start_pos: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1).

+		Immutable
substring(input: varbit, start_pos: int, length: int) → varbit

Returns a bit subarray of input starting at start_pos (count starts at 1) and including up to length characters.

+		Immutable
substring_index(input: string, delim: string, count: int) → string

Returns a substring of input before count occurrences of delim. +If count is positive, the leftmost part is returned. If count is negative, the rightmost part is returned.

+		Immutable
to_char_with_style(date: date, datestyle: string) → string

Convert an date to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_char_with_style(interval: interval, style: string) → string

Convert an interval to a string using the given IntervalStyle.

+		Immutable
to_char_with_style(timestamp: timestamp, datestyle: string) → string

Convert an timestamp to a string assuming the string is formatted using the given DateStyle.

+		Immutable
to_english(val: int) → string

This function enunciates the value of its argument using English cardinals.

+		Immutable
to_hex(val: bytes) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: int) → string

Converts val to its hexadecimal representation.

+		Immutable
to_hex(val: string) → string

Converts val to its hexadecimal representation.

+		Immutable
to_ip(val: string) → bytes

Converts the character string representation of an IP to its byte string representation.

+		Immutable
to_uuid(val: string) → bytes

Converts the character string representation of a UUID to its byte string representation.

+		Immutable
translate(input: string, find: string, replace: string) → string

In input, replaces the first character from find with the first character in replace; repeat for each character in find.

+

For example, translate('doggie', 'dog', '123'); returns 1233ie.

+		Immutable
ulid_to_uuid(val: string) → uuid

Converts a ULID string to its UUID-encoded representation.

+		Immutable
unaccent(val: string) → string

Removes accents (diacritic signs) from the text provided in val.

+		Immutable
upper(val: string) → string

Converts all characters in val to their to their upper-case equivalents.

+		Immutable
+ +### System info functions + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cluster_logical_timestamp() → decimal

Returns the logical time of the current transaction as +a CockroachDB HLC in decimal form.

+

Note that uses of this function disable server-side optimizations and +may increase either contention or retry errors, or both.

+

Returns an error if run in a transaction with an isolation level weaker than SERIALIZABLE.

+		Volatile
current_database() → string

Returns the current database.

+		Stable
current_schema() → string

Returns the current schema.

+		Stable
current_schemas(include_pg_catalog: bool) → string[]

Returns the valid schemas in the search path.

+		Stable
current_user() → string

Returns the current user. This function is provided for compatibility with PostgreSQL.

+		Stable
information_schema.crdb_datums_to_bytes(any...) → bytes

Converts datums into key-encoded bytes. Supports NULLs and all data types which may be used in index keys

+		Immutable
session_user() → string

Returns the session user. This function is provided for compatibility with PostgreSQL.

+		Stable
to_regclass(text: string) → regtype

Translates a textual relation name to its OID

+		Stable
to_regnamespace(text: string) → regtype

Translates a textual schema name to its OID

+		Stable
to_regproc(text: string) → regtype

Translates a textual function or procedure name to its OID

+		Stable
to_regprocedure(text: string) → regtype

Translates a textual function or procedure name(with argument types) to its OID

+		Stable
to_regrole(text: string) → regtype

Translates a textual role name to its OID

+		Stable
to_regtype(text: string) → regtype

Translates a textual type name to its OID

+		Stable
version() → string

Returns the node’s version of CockroachDB.

+		Volatile
+ +### System repair functions + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
information_schema.crdb_delete_statement_hints(rowid: int) → int

This function deletes a statement hint by its row ID. It returns the number of deleted rows.

+		Volatile
information_schema.crdb_delete_statement_hints(statement_fingerprint: string) → int

This function deletes all statement hints matching the given statement fingerprint. The statement fingerprint argument is normalized before matching. It returns the number of deleted rows.

+		Volatile
information_schema.crdb_delete_statement_hints(statement_fingerprint: string, database: string) → int

This function deletes all statement hints matching the given statement fingerprint and database. The statement fingerprint argument is normalized before matching. It returns the number of deleted rows.

+		Volatile
information_schema.crdb_enable_statement_hints(enabled: bool, rowid: int) → int

This function enables or disables the statement hint with the given row ID. It returns the number of affected rows.

+		Volatile
information_schema.crdb_enable_statement_hints(enabled: bool, statement_fingerprint: string) → int

This function enables or disables all statement hints matching the given statement fingerprint. The statement fingerprint argument is normalized before matching. It returns the number of affected rows.

+		Volatile
information_schema.crdb_enable_statement_hints(enabled: bool, statement_fingerprint: string, database: string) → int

This function enables or disables all statement hints matching the given statement fingerprint and database. The statement fingerprint argument is normalized before matching. It returns the number of affected rows.

+		Volatile
information_schema.crdb_rewrite_inline_hints(statement_fingerprint: string, donor_sql: string) → int

This function adds an inline-hints rewrite rule for a statement fingerprint. It returns the hint ID of the newly created rewrite rule. The rewrite rule only applies to matching statement fingerprints. It first removes all inline hints from the target statement, and then copies inline hints from the donor statement.

+		Volatile
information_schema.crdb_rewrite_inline_hints(statement_fingerprint: string, donor_sql: string, database: string) → int

This function adds an inline-hints rewrite rule for a statement fingerprint, scoped to the given database. It returns the hint ID of the newly created rewrite rule. The rewrite rule only applies to matching statement fingerprints when the current database matches the specified database. It first removes all inline hints from the target statement, and then copies inline hints from the donor statement.

+		Volatile
information_schema.crdb_set_session_variable_hint(statement_fingerprint: string, variable_name: string, variable_value: string) → int

This function adds a session variable override hint for a statement fingerprint. It returns the hint ID of the newly created hint. The hint only applies to matching statement fingerprints and temporarily overrides the specified session variable for that statement only. Safe variables can be hinted without restrictions. Unsafe variables cannot be hinted when sql_safe_updates is enabled.

+		Volatile
information_schema.crdb_set_session_variable_hint(statement_fingerprint: string, variable_name: string, variable_value: string, database: string) → int

This function adds a session variable override hint for a statement fingerprint, scoped to the given database. It returns the hint ID of the newly created hint. The hint only applies to matching statement fingerprints when the current database matches the specified database, and temporarily overrides the specified session variable for that statement only. Safe variables can be hinted without restrictions. Unsafe variables cannot be hinted when sql_safe_updates is enabled.

+		Volatile
+ +### TIMETZ functions + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
current_time() → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time() → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
current_time(precision: int) → time

Returns the current transaction’s time with no time zone.

+		Stable
current_time(precision: int) → timetz

Returns the current transaction’s time with time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime() → timetz

Returns the current transaction’s time with time zone.

+		Stable
localtime(precision: int) → time

Returns the current transaction’s time with no time zone.

+

This function is the preferred overload and will be evaluated by default.

+		Stable
localtime(precision: int) → timetz

Returns the current transaction’s time with time zone.

+		Stable
+ +### Trigrams functions + + + + + + +
Function → ReturnsDescriptionVolatility
show_trgm(input: string) → string[]

Returns an array of all the trigrams in the given string.

+		Immutable
similarity(left: string, right: string) → float

Returns a number that indicates how similar the two arguments are. The range of the result is zero (indicating that the two strings are completely dissimilar) to one (indicating that the two strings are identical).

+		Immutable
+ +### UUID functions + + + + + +
Function → ReturnsDescriptionVolatility
uuid_to_ulid(val: uuid) → string

Converts a UUID-encoded ULID to its string representation.

+		Immutable
+ +### Compatibility functions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
acldefault(type: "char", ownerId: oid) → aclitem[]

Returns the default access privileges for an object of the given type belonging to the given owner.

+		Immutable
col_description(table_oid: oid, column_number: int) → string

Returns the comment for a table column, which is specified by the OID of its table and its column number. (obj_description cannot be used for table columns, since columns do not have OIDs of their own.)

+		Stable
current_setting(setting_name: string) → string

System info

+		Stable
current_setting(setting_name: string, missing_ok: bool) → string

System info

+		Stable
format_type(type_oid: oid, typemod: int) → string

Returns the SQL name of a data type that is identified by its type OID and possibly a type modifier. Currently, the type modifier is ignored.

+		Stable
getdatabaseencoding() → string

Returns the current encoding name used by the database.

+		Stable
has_any_column_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_any_column_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for any column of table.

+		Stable
has_column_privilege(table: string, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: string, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: int, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(table: oid, column: string, privilege: string) → bool

Returns whether or not the current user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: string, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: string, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: int, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_column_privilege(user: oid, table: oid, column: string, privilege: string) → bool

Returns whether or not the user has privileges for column.

+		Stable
has_database_privilege(database: string, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(database: oid, privilege: string) → bool

Returns whether or not the current user has privileges for database.

+		Stable
has_database_privilege(user: string, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: string, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: string, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_database_privilege(user: oid, database: oid, privilege: string) → bool

Returns whether or not the user has privileges for database.

+		Stable
has_foreign_data_wrapper_privilege(fdw: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(fdw: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: string, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_foreign_data_wrapper_privilege(user: oid, fdw: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign-data wrapper.

+		Stable
has_function_privilege(function: string, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(function: oid, privilege: string) → bool

Returns whether or not the current user has privileges for function.

+		Stable
has_function_privilege(user: string, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: string, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: string, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_function_privilege(user: oid, function: oid, privilege: string) → bool

Returns whether or not the user has privileges for function.

+		Stable
has_language_privilege(language: string, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(language: oid, privilege: string) → bool

Returns whether or not the current user has privileges for language.

+		Stable
has_language_privilege(user: string, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: string, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: string, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_language_privilege(user: oid, language: oid, privilege: string) → bool

Returns whether or not the user has privileges for language.

+		Stable
has_schema_privilege(schema: string, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(schema: oid, privilege: string) → bool

Returns whether or not the current user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: string, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: string, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_schema_privilege(user: oid, schema: oid, privilege: string) → bool

Returns whether or not the user has privileges for schema.

+		Stable
has_sequence_privilege(sequence: string, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(sequence: oid, privilege: string) → bool

Returns whether or not the current user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: string, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: string, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_sequence_privilege(user: oid, sequence: oid, privilege: string) → bool

Returns whether or not the user has privileges for sequence.

+		Stable
has_server_privilege(server: string, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(server: oid, privilege: string) → bool

Returns whether or not the current user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: string, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: string, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_server_privilege(user: oid, server: oid, privilege: string) → bool

Returns whether or not the user has privileges for foreign server.

+		Stable
has_system_privilege(privilege: string) → bool

Returns whether or not the current user has privileges for system.

+		Stable
has_system_privilege(user: string, privilege: string) → bool

Returns whether or not the user has privileges for system.

+		Stable
has_system_privilege(user: oid, privilege: string) → bool

Returns whether or not the user has privileges for system.

+		Stable
has_table_privilege(table: string, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(table: oid, privilege: string) → bool

Returns whether or not the current user has privileges for table.

+		Stable
has_table_privilege(user: string, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: string, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: string, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_table_privilege(user: oid, table: oid, privilege: string) → bool

Returns whether or not the user has privileges for table.

+		Stable
has_tablespace_privilege(tablespace: string, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(tablespace: oid, privilege: string) → bool

Returns whether or not the current user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: string, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: string, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_tablespace_privilege(user: oid, tablespace: oid, privilege: string) → bool

Returns whether or not the user has privileges for tablespace.

+		Stable
has_type_privilege(type: string, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(type: oid, privilege: string) → bool

Returns whether or not the current user has privileges for type.

+		Stable
has_type_privilege(user: string, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: string, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: string, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
has_type_privilege(user: oid, type: oid, privilege: string) → bool

Returns whether or not the user has privileges for type.

+		Stable
information_schema._pg_numeric_precision(typid: oid, typmod: int4) → int

Returns the precision of the given type with type modifier

+		Immutable
information_schema._pg_numeric_precision_radix(typid: oid, typmod: int4) → int

Returns the radix of the given type with type modifier

+		Immutable
information_schema._pg_numeric_scale(typid: oid, typmod: int4) → int

Returns the scale of the given type with type modifier

+		Immutable
makeaclitem(grantee: oid, grantor: oid, privileges: string, is_grantable: bool) → aclitem

Constructs an aclitem from the given grantee, grantor, privileges, and grant option.

+		Immutable
nameconcatoid(name: string, oid: oid) → name

Used in the information_schema to produce specific_name columns, which are supposed to be unique per schema. The result is the same as ($1::text || ‘_’ || $2::text)::name except that, if it would not fit in 63 characters, we make it do so by truncating the name input (not the oid).

+		Immutable
obj_description(object_oid: oid) → string

Returns the comment for a database object specified by its OID alone. This is deprecated since there is no guarantee that OIDs are unique across different system catalogs; therefore, the wrong comment might be returned.

+		Stable
obj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a database object specified by its OID and the name of the containing system catalog. For example, obj_description(123456, ‘pg_class’) would retrieve the comment for the table with OID 123456.

+		Stable
oidvectortypes(vector: oidvector) → string

Generates a comma seperated string of type names from an oidvector.

+		Stable
pg_backend_pid() → int

Returns a numerical ID attached to this session. This ID is part of the query cancellation key used by the wire protocol. This function was only added for compatibility, and unlike in Postgres, the returned value does not correspond to a real process ID.

+		Stable
pg_collation_for(str: anyelement) → string

Returns the collation of the argument

+		Stable
pg_column_is_updatable(reloid: oid, attnum: int2, include_triggers: bool) → bool

Returns whether the given column can be updated.

+		Stable
pg_column_size(any...) → int

Return size in bytes of the column provided as an argument

+		Stable
pg_function_is_visible(oid: oid) → bool

Returns whether the function with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_get_constraintdef(constraint_oid: oid) → string

Returns the definition of the specified constraint.

+		Stable
pg_get_constraintdef(constraint_oid: oid, pretty_bool: bool) → string

Returns the definition of the specified constraint.

+		Stable
pg_get_function_arg_default(func_oid: oid, arg_num: int4) → string

Get textual representation of a function argument’s default value. The second argument of this function is the argument number among all arguments (i.e. proallargtypes, not proargtypes), starting with 1, because that’s how information_schema.sql uses it.

+		Stable
pg_get_function_arguments(func_oid: oid) → string

Returns the argument list (with defaults) necessary to identify a function, in the form it would need to appear in within CREATE FUNCTION.

+		Stable
pg_get_function_identity_arguments(func_oid: oid) → string

Returns the argument list (without defaults) necessary to identify a function, in the form it would need to appear in within ALTER FUNCTION, for instance.

+		Stable
pg_get_function_result(func_oid: oid) → string

Returns the types of the result of the specified function.

+		Stable
pg_get_functiondef(func_oid: oid) → string

For user-defined functions, returns the definition of the specified function. For builtin functions, returns the name of the function.

+		Stable
pg_get_indexdef(index_oid: oid) → string

Gets the CREATE INDEX command for index

+		Stable
pg_get_indexdef(index_oid: oid, column_no: int, pretty_bool: bool) → string

Gets the CREATE INDEX command for index, or definition of just one index column when given a non-zero column number

+		Stable
pg_get_serial_sequence(table_name: string, column_name: string) → string

Returns the name of the sequence used by the given column_name in the table table_name.

+		Stable
pg_get_triggerdef(trigger_oid: oid) → string

Returns the CREATE TRIGGER statement for the specified trigger.

+		Stable
pg_get_triggerdef(trigger_oid: oid, pretty_bool: bool) → string

Returns the CREATE TRIGGER statement for the specified trigger.

+		Stable
pg_get_viewdef(view_oid: oid) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_get_viewdef(view_oid: oid, pretty_bool: bool) → string

Returns the CREATE statement for an existing view.

+		Stable
pg_has_role(role: string, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(role: oid, privilege: string) → bool

Returns whether or not the current user has privileges for role.

+		Stable
pg_has_role(user: string, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: string, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: string, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_has_role(user: oid, role: oid, privilege: string) → bool

Returns whether or not the user has privileges for role.

+		Stable
pg_is_other_temp_schema(oid: oid) → bool

Returns true if the given OID is the OID of another session’s temporary schema. (This can be useful, for example, to exclude other sessions’ temporary tables from a catalog display.)

+		Stable
pg_my_temp_schema() → oid

Returns the OID of the current session’s temporary schema, or zero if it has none (because it has not created any temporary tables).

+		Stable
pg_relation_is_updatable(reloid: oid, include_triggers: bool) → int4

Returns the update events the relation supports.

+		Stable
pg_sequence_last_value(sequence_oid: oid) → int

Returns the last value generated by a sequence, or NULL if the sequence has not been used yet.

+		Volatile
pg_sleep(seconds: float) → bool

pg_sleep makes the current session’s process sleep until seconds seconds have elapsed. seconds is a value of type double precision, so fractional-second delays can be specified.

+		Volatile
pg_table_is_visible(oid: oid) → bool

Returns whether the table with the given OID belongs to one of the schemas on the search path.

+		Stable
pg_trigger_depth() → int

Returns the current nesting level of PostgreSQL triggers (0 if not called, directly or indirectly, from inside a trigger).

+		Volatile
pg_type_is_visible(oid: oid) → bool

Returns whether the type with the given OID belongs to one of the schemas on the search path.

+		Stable
set_config(setting_name: string, new_value: string, is_local: bool) → string

System info

+		Volatile
shobj_description(object_oid: oid, catalog_name: string) → string

Returns the comment for a shared database object specified by its OID and the name of the containing system catalog. This is just like obj_description except that it is used for retrieving comments on shared objects (e.g. databases).

+		Stable
+ diff --git a/src/current/_includes/cockroach-generated/release-26.2/sql/operators.md b/src/current/_includes/cockroach-generated/release-26.2/sql/operators.md new file mode 100644 index 00000000000..e79484b0754 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-26.2/sql/operators.md @@ -0,0 +1,684 @@ + + + + + +
#Return
int # intint
varbit # varbitvarbit
+ + + + +
#>Return
jsonb #> string[]jsonb
+ + + + +
#>>Return
jsonb #>> string[]string
+ + + + + + + + + +
%Return
decimal % decimaldecimal
decimal % intdecimal
float % floatfloat
int % decimaldecimal
int % intint
string % stringbool
+ + + + + + +
&Return
inet & inetinet
int & intint
varbit & varbitvarbit
+ + + + + + + + + +
&&Return
anyelement && anyelementbool
box2d && box2dbool
box2d && geometrybool
geometry && box2dbool
geometry && geometrybool
inet && inetbool
+ + + + + + + + + + + + + + + +
*Return
decimal * decimaldecimal
decimal * intdecimal
decimal * intervalinterval
float * floatfloat
float * intervalinterval
int * decimaldecimal
int * intint
int * intervalinterval
interval * decimalinterval
interval * floatinterval
interval * intinterval
vector * vectorvector
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+Return
+decimaldecimal
+floatfloat
+intint
+intervalinterval
date + intdate
date + intervaltimestamp
date + timetimestamp
date + timetztimestamptz
decimal + decimaldecimal
decimal + intdecimal
decimal + pg_lsnpg_lsn
float + floatfloat
inet + intinet
int + datedate
int + decimaldecimal
int + inetinet
int + intint
interval + datetimestamp
interval + intervalinterval
interval + timetime
interval + timestamptimestamp
interval + timestamptztimestamptz
interval + timetztimetz
pg_lsn + decimalpg_lsn
time + datetimestamp
time + intervaltime
timestamp + intervaltimestamp
timestamptz + intervaltimestamptz
timetz + datetimestamptz
timetz + intervaltimetz
vector + vectorvector
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
-Return
-decimaldecimal
-floatfloat
-intint
-intervalinterval
date - dateint
date - intdate
date - intervaltimestamp
date - timetimestamp
decimal - decimaldecimal
decimal - intdecimal
float - floatfloat
inet - inetint
inet - intinet
int - decimaldecimal
int - intint
interval - intervalinterval
jsonb - intjsonb
jsonb - stringjsonb
jsonb - string[]jsonb
pg_lsn - decimalpg_lsn
pg_lsn - pg_lsndecimal
time - intervaltime
time - timeinterval
timestamp - intervaltimestamp
timestamp - timestampinterval
timestamp - timestamptzinterval
timestamptz - intervaltimestamptz
timestamptz - timestampinterval
timestamptz - timestamptzinterval
timetz - intervaltimetz
vector - vectorvector
+ + + + + +
->Return
jsonb -> intjsonb
jsonb -> stringjsonb
+ + + + + +
->>Return
jsonb ->> intstring
jsonb ->> stringstring
+ + + + + + + + + + +
/Return
decimal / decimaldecimal
decimal / intdecimal
float / floatfloat
int / decimaldecimal
int / intdecimal
interval / floatinterval
interval / intinterval
+ + + + + + + + +
//Return
decimal // decimaldecimal
decimal // intdecimal
float // floatfloat
int // decimaldecimal
int // intint
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<Return
anyenum < anyenumbool
bool < boolbool
bool[] < bool[]bool
box2d < box2dbool
bpchar < bpcharbool
bytes < bytesbool
bytes[] < bytes[]bool
collatedstring < collatedstringbool
collatedstring{*} < collatedstring{*}bool
date < datebool
date < timestampbool
date < timestamptzbool
date[] < date[]bool
decimal < decimalbool
decimal < floatbool
decimal < intbool
decimal[] < decimal[]bool
float < decimalbool
float < floatbool
float < intbool
float[] < float[]bool
geography < geographybool
geometry < geometrybool
inet < inetbool
inet[] < inet[]bool
int < decimalbool
int < floatbool
int < intbool
int < oidbool
int[] < int[]bool
interval < intervalbool
interval[] < interval[]bool
jsonb < jsonbbool
ltree < ltreebool
oid < intbool
oid < oidbool
pg_lsn < pg_lsnbool
refcursor < refcursorbool
string < stringbool
string[] < string[]bool
time < timebool
time < timetzbool
time[] < time[]bool
timestamp < datebool
timestamp < timestampbool
timestamp < timestamptzbool
timestamp[] < timestamp[]bool
timestamptz < datebool
timestamptz < timestampbool
timestamptz < timestamptzbool
timestamptz < timestamptzbool
timetz < timebool
timetz < timetzbool
tuple < tuplebool
uuid < uuidbool
uuid[] < uuid[]bool
varbit < varbitbool
vector < vectorbool
+ + + + +
<#>Return
vector <#> vectorfloat
+ + + + +
<->Return
vector <-> vectorfloat
+ + + + + + +
<<Return
inet << inetbool
int << intint
varbit << intvarbit
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
<=Return
anyenum <= anyenumbool
bool <= boolbool
bool[] <= bool[]bool
box2d <= box2dbool
bpchar <= bpcharbool
bytes <= bytesbool
bytes[] <= bytes[]bool
collatedstring <= collatedstringbool
collatedstring{*} <= collatedstring{*}bool
date <= datebool
date <= timestampbool
date <= timestamptzbool
date[] <= date[]bool
decimal <= decimalbool
decimal <= floatbool
decimal <= intbool
decimal[] <= decimal[]bool
float <= decimalbool
float <= floatbool
float <= intbool
float[] <= float[]bool
geography <= geographybool
geometry <= geometrybool
inet <= inetbool
inet[] <= inet[]bool
int <= decimalbool
int <= floatbool
int <= intbool
int <= oidbool
int[] <= int[]bool
interval <= intervalbool
interval[] <= interval[]bool
jsonb <= jsonbbool
ltree <= ltreebool
oid <= intbool
oid <= oidbool
pg_lsn <= pg_lsnbool
refcursor <= refcursorbool
string <= stringbool
string[] <= string[]bool
time <= timebool
time <= timetzbool
time[] <= time[]bool
timestamp <= datebool
timestamp <= timestampbool
timestamp <= timestamptzbool
timestamp[] <= timestamp[]bool
timestamptz <= datebool
timestamptz <= timestampbool
timestamptz <= timestamptzbool
timestamptz <= timestamptzbool
timetz <= timebool
timetz <= timetzbool
tuple <= tuplebool
uuid <= uuidbool
uuid[] <= uuid[]bool
varbit <= varbitbool
vector <= vectorbool
+ + + + +
<=>Return
vector <=> vectorfloat
+ + + + + + +
<@Return
anyelement <@ anyelementbool
jsonb <@ jsonbbool
ltree <@ ltreebool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
=Return
anyenum = anyenumbool
bool = boolbool
bool[] = bool[]bool
box2d = box2dbool
bpchar = bpcharbool
bytes = bytesbool
bytes[] = bytes[]bool
collatedstring = collatedstringbool
collatedstring{*} = collatedstring{*}bool
date = datebool
date = timestampbool
date = timestamptzbool
date[] = date[]bool
decimal = decimalbool
decimal = floatbool
decimal = intbool
decimal[] = decimal[]bool
float = decimalbool
float = floatbool
float = intbool
float[] = float[]bool
geography = geographybool
geometry = geometrybool
inet = inetbool
inet[] = inet[]bool
int = decimalbool
int = floatbool
int = intbool
int = oidbool
int[] = int[]bool
interval = intervalbool
interval[] = interval[]bool
jsonb = jsonbbool
ltree = ltreebool
oid = intbool
oid = oidbool
pg_lsn = pg_lsnbool
refcursor = refcursorbool
string = stringbool
string[] = string[]bool
time = timebool
time = timetzbool
time[] = time[]bool
timestamp = datebool
timestamp = timestampbool
timestamp = timestamptzbool
timestamp[] = timestamp[]bool
timestamptz = datebool
timestamptz = timestampbool
timestamptz = timestamptzbool
timestamptz = timestamptzbool
timetz = timebool
timetz = timetzbool
tsquery = tsquerybool
tsvector = tsvectorbool
tuple = tuplebool
uuid = uuidbool
uuid[] = uuid[]bool
varbit = varbitbool
vector = vectorbool
+ + + + + + +
>>Return
inet >> inetbool
int >> intint
varbit >> intvarbit
+ + + + +
?Return
jsonb ? stringbool
+ + + + +
?&Return
jsonb ?& string[]bool
+ + + + +
?<@Return
ltree ?<@ ltreeltree
+ + + + +
?@>Return
ltree ?@> ltreeltree
+ + + + +
?|Return
jsonb ?| string[]bool
+ + + + + + +
@>Return
anyelement @> anyelementbool
jsonb @> jsonbbool
ltree @> ltreebool
+ + + + + +
@@Return
tsquery @@ tsvectorbool
tsvector @@ tsquerybool
+ + + + +
ILIKEReturn
string ILIKE stringbool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
INReturn
anyenum IN tuplebool
bool IN tuplebool
box2d IN tuplebool
bpchar IN tuplebool
bytes IN tuplebool
collatedstring IN tuplebool
date IN tuplebool
decimal IN tuplebool
float IN tuplebool
geography IN tuplebool
geometry IN tuplebool
inet IN tuplebool
int IN tuplebool
interval IN tuplebool
jsonb IN tuplebool
ltree IN tuplebool
oid IN tuplebool
pg_lsn IN tuplebool
refcursor IN tuplebool
string IN tuplebool
time IN tuplebool
timestamp IN tuplebool
timestamptz IN tuplebool
timetz IN tuplebool
tuple IN tuplebool
uuid IN tuplebool
varbit IN tuplebool
vector IN tuplebool
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IS NOT DISTINCT FROMReturn
anyelement IS NOT DISTINCT FROM unknownbool
anyenum IS NOT DISTINCT FROM anyenumbool
bool IS NOT DISTINCT FROM boolbool
bool[] IS NOT DISTINCT FROM bool[]bool
box2d IS NOT DISTINCT FROM box2dbool
bpchar IS NOT DISTINCT FROM bpcharbool
bytes IS NOT DISTINCT FROM bytesbool
bytes[] IS NOT DISTINCT FROM bytes[]bool
collatedstring IS NOT DISTINCT FROM collatedstringbool
collatedstring{*} IS NOT DISTINCT FROM collatedstring{*}bool
date IS NOT DISTINCT FROM datebool
date IS NOT DISTINCT FROM timestampbool
date IS NOT DISTINCT FROM timestamptzbool
date[] IS NOT DISTINCT FROM date[]bool
decimal IS NOT DISTINCT FROM decimalbool
decimal IS NOT DISTINCT FROM floatbool
decimal IS NOT DISTINCT FROM intbool
decimal[] IS NOT DISTINCT FROM decimal[]bool
float IS NOT DISTINCT FROM decimalbool
float IS NOT DISTINCT FROM floatbool
float IS NOT DISTINCT FROM intbool
float[] IS NOT DISTINCT FROM float[]bool
geography IS NOT DISTINCT FROM geographybool
geometry IS NOT DISTINCT FROM geometrybool
inet IS NOT DISTINCT FROM inetbool
inet[] IS NOT DISTINCT FROM inet[]bool
int IS NOT DISTINCT FROM decimalbool
int IS NOT DISTINCT FROM floatbool
int IS NOT DISTINCT FROM intbool
int IS NOT DISTINCT FROM oidbool
int[] IS NOT DISTINCT FROM int[]bool
interval IS NOT DISTINCT FROM intervalbool
interval[] IS NOT DISTINCT FROM interval[]bool
jsonb IS NOT DISTINCT FROM jsonbbool
jsonpath IS NOT DISTINCT FROM jsonpathbool
ltree IS NOT DISTINCT FROM ltreebool
oid IS NOT DISTINCT FROM intbool
oid IS NOT DISTINCT FROM oidbool
pg_lsn IS NOT DISTINCT FROM pg_lsnbool
refcursor IS NOT DISTINCT FROM refcursorbool
string IS NOT DISTINCT FROM stringbool
string[] IS NOT DISTINCT FROM string[]bool
time IS NOT DISTINCT FROM timebool
time IS NOT DISTINCT FROM timetzbool
time[] IS NOT DISTINCT FROM time[]bool
timestamp IS NOT DISTINCT FROM datebool
timestamp IS NOT DISTINCT FROM timestampbool
timestamp IS NOT DISTINCT FROM timestamptzbool
timestamp[] IS NOT DISTINCT FROM timestamp[]bool
timestamptz IS NOT DISTINCT FROM datebool
timestamptz IS NOT DISTINCT FROM timestampbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timestamptz IS NOT DISTINCT FROM timestamptzbool
timetz IS NOT DISTINCT FROM timebool
timetz IS NOT DISTINCT FROM timetzbool
tsquery IS NOT DISTINCT FROM tsquerybool
tsvector IS NOT DISTINCT FROM tsvectorbool
tuple IS NOT DISTINCT FROM tuplebool
unknown IS NOT DISTINCT FROM unknownbool
unknown IS NOT DISTINCT FROM voidbool
uuid IS NOT DISTINCT FROM uuidbool
uuid[] IS NOT DISTINCT FROM uuid[]bool
varbit IS NOT DISTINCT FROM varbitbool
vector IS NOT DISTINCT FROM vectorbool
void IS NOT DISTINCT FROM unknownbool
+ + + + + +
LIKEReturn
collatedstring LIKE collatedstringbool
string LIKE stringbool
+ + + + +
SIMILAR TOReturn
string SIMILAR TO stringbool
+ + + + + + + + +
^Return
decimal ^ decimaldecimal
decimal ^ intdecimal
float ^ floatfloat
int ^ decimaldecimal
int ^ intint
+ + + + + + +
|Return
inet | inetinet
int | intint
varbit | varbitvarbit
+ + + + + +
|/Return
|/decimaldecimal
|/floatfloat
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
||Return
bool || bool[]bool[]
bool || stringstring
bool[] || boolbool[]
bool[] || bool[]bool[]
box2d || box2dbox2d
box2d || stringstring
bytes || bytesbytes
bytes || bytes[]bytes[]
bytes[] || bytesbytes[]
bytes[] || bytes[]bytes[]
date || date[]date[]
date || stringstring
date[] || datedate[]
date[] || date[]date[]
decimal || decimal[]decimal[]
decimal || stringstring
decimal[] || decimaldecimal[]
decimal[] || decimal[]decimal[]
float || float[]float[]
float || stringstring
float[] || floatfloat[]
float[] || float[]float[]
geography || geographygeography
geography || stringstring
geometry || geometrygeometry
geometry || stringstring
inet || inet[]inet[]
inet || stringstring
inet[] || inetinet[]
inet[] || inet[]inet[]
int || int[]int[]
int || stringstring
int[] || intint[]
int[] || int[]int[]
interval || interval[]interval[]
interval || stringstring
interval[] || intervalinterval[]
interval[] || interval[]interval[]
jsonb || jsonbjsonb
jsonb || stringstring
ltree || ltreeltree
ltree || stringstring
oid || oidoid
oid || stringstring
pg_lsn || pg_lsnpg_lsn
pg_lsn || stringstring
refcursor || refcursorrefcursor
refcursor || stringstring
string || boolstring
string || box2dstring
string || datestring
string || decimalstring
string || floatstring
string || geographystring
string || geometrystring
string || inetstring
string || intstring
string || intervalstring
string || jsonbstring
string || ltreestring
string || oidstring
string || pg_lsnstring
string || refcursorstring
string || stringstring
string || string[]string[]
string || timestring
string || timestampstring
string || timestamptzstring
string || timetzstring
string || tuplestring
string || uuidstring
string || varbitstring
string[] || stringstring[]
string[] || string[]string[]
time || stringstring
time || time[]time[]
time[] || timetime[]
time[] || time[]time[]
timestamp || stringstring
timestamp || timestamp[]timestamp[]
timestamp[] || timestamptimestamp[]
timestamp[] || timestamp[]timestamp[]
timestamptz || stringstring
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timestamptz || timestamptztimestamptz
timetz || stringstring
timetz || timetztimetz
tuple || stringstring
uuid || stringstring
uuid || uuid[]uuid[]
uuid[] || uuiduuid[]
uuid[] || uuid[]uuid[]
varbit || stringstring
varbit || varbitvarbit
+ + + + + +
||/Return
||/decimaldecimal
||/floatfloat
+ + + + + + + + + + + +
~Return
~inetinet
~intint
~varbitvarbit
box2d ~ box2dbool
box2d ~ geometrybool
geometry ~ box2dbool
geometry ~ geometrybool
string ~ stringbool
+ + + + +
~*Return
string ~* stringbool
diff --git a/src/current/_includes/cockroach-generated/release-26.2/sql/window_functions.md b/src/current/_includes/cockroach-generated/release-26.2/sql/window_functions.md new file mode 100644 index 00000000000..321cc02ccf9 --- /dev/null +++ b/src/current/_includes/cockroach-generated/release-26.2/sql/window_functions.md @@ -0,0 +1,431 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Function → ReturnsDescriptionVolatility
cume_dist() → float

Calculates the relative rank of the current row: (number of rows preceding or peer with current row) / (total rows).

+		Immutable
dense_rank() → int

Calculates the rank of the current row without gaps; this function counts peer groups.

+		Immutable
first_value(val: bool) → bool

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: bytes) → bytes

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: date) → date

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: decimal) → decimal

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: float) → float

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: inet) → inet

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: int) → int

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: interval) → interval

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: string) → string

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: time) → time

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: uuid) → uuid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: box2d) → box2d

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geography) → geography

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: geometry) → geometry

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: ltree) → ltree

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: oid) → oid

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: timetz) → timetz

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
first_value(val: varbit) → varbit

Returns val evaluated at the row that is the first row of the window frame.

+		Immutable
lag(val: bool) → bool

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: bytes) → bytes

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: date) → date

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: date, n: int) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: decimal) → decimal

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: float) → float

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: float, n: int) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: inet) → inet

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: int) → int

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: int, n: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: interval) → interval

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: string) → string

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: string, n: int) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: time) → time

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: time, n: int) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamp) → timestamp

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz) → timestamptz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: uuid) → uuid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: box2d) → box2d

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geography) → geography

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: geometry) → geometry

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: jsonb) → jsonb

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: ltree) → ltree

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: ltree, n: int) → ltree

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: ltree, n: int, default: ltree) → ltree

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: oid) → oid

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn) → pg_lsn

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: refcursor) → refcursor

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: timetz) → timetz

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lag(val: varbit) → varbit

Returns val evaluated at the previous row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lag(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lag(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows before the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
last_value(val: bool) → bool

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: bytes) → bytes

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: date) → date

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: decimal) → decimal

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: float) → float

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: inet) → inet

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: int) → int

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: interval) → interval

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: string) → string

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: time) → time

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamp) → timestamp

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timestamptz) → timestamptz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: uuid) → uuid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: box2d) → box2d

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geography) → geography

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: geometry) → geometry

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: jsonb) → jsonb

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: ltree) → ltree

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: oid) → oid

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: pg_lsn) → pg_lsn

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: refcursor) → refcursor

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: timetz) → timetz

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
last_value(val: varbit) → varbit

Returns val evaluated at the row that is the last row of the window frame.

+		Immutable
lead(val: bool) → bool

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bool, n: int) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bool, n: int, default: bool) → bool

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: bytes) → bytes

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: bytes, n: int) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: bytes, n: int, default: bytes) → bytes

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: date) → date

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: date, n: int) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: date, n: int, default: date) → date

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: decimal) → decimal

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: decimal, n: int) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: decimal, n: int, default: decimal) → decimal

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: float) → float

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: float, n: int) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: float, n: int, default: float) → float

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: inet) → inet

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: inet, n: int) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: inet, n: int, default: inet) → inet

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: int) → int

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: int, n: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: int, n: int, default: int) → int

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: interval) → interval

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: interval, n: int) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: interval, n: int, default: interval) → interval

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: string) → string

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: string, n: int) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: string, n: int, default: string) → string

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: time) → time

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: time, n: int) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: time, n: int, default: time) → time

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamp) → timestamp

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamp, n: int, default: timestamp) → timestamp

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz) → timestamptz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timestamptz, n: int, default: timestamptz) → timestamptz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: uuid) → uuid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: uuid, n: int) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: uuid, n: int, default: uuid) → uuid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: box2d) → box2d

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: box2d, n: int) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: box2d, n: int, default: box2d) → box2d

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geography) → geography

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geography, n: int) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geography, n: int, default: geography) → geography

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: geometry) → geometry

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: geometry, n: int) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: geometry, n: int, default: geometry) → geometry

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: jsonb) → jsonb

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: jsonb, n: int, default: jsonb) → jsonb

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: ltree) → ltree

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: ltree, n: int) → ltree

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: ltree, n: int, default: ltree) → ltree

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: oid) → oid

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: oid, n: int) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: oid, n: int, default: oid) → oid

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn) → pg_lsn

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: pg_lsn, n: int, default: pg_lsn) → pg_lsn

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: refcursor) → refcursor

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: refcursor, n: int, default: refcursor) → refcursor

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: timetz) → timetz

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: timetz, n: int) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: timetz, n: int, default: timetz) → timetz

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
lead(val: varbit) → varbit

Returns val evaluated at the following row within current row’s partition; if there is no such row, instead returns null.

+		Immutable
lead(val: varbit, n: int) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such row, instead returns null. n is evaluated with respect to the current row.

+		Immutable
lead(val: varbit, n: int, default: varbit) → varbit

Returns val evaluated at the row that is n rows after the current row within its partition; if there is no such, row, instead returns default (which must be of the same type as val). Both n and default are evaluated with respect to the current row.

+		Immutable
nth_value(val: bool, n: int) → bool

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: bytes, n: int) → bytes

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: date, n: int) → date

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: decimal, n: int) → decimal

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: float, n: int) → float

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: inet, n: int) → inet

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: int, n: int) → int

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: interval, n: int) → interval

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: string, n: int) → string

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: time, n: int) → time

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamp, n: int) → timestamp

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timestamptz, n: int) → timestamptz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: uuid, n: int) → uuid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: box2d, n: int) → box2d

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geography, n: int) → geography

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: geometry, n: int) → geometry

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: jsonb, n: int) → jsonb

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: ltree, n: int) → ltree

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: oid, n: int) → oid

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: pg_lsn, n: int) → pg_lsn

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: refcursor, n: int) → refcursor

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: timetz, n: int) → timetz

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
nth_value(val: varbit, n: int) → varbit

Returns val evaluated at the row that is the nth row of the window frame (counting from 1); null if no such row.

+		Immutable
ntile(n: int) → int

Calculates an integer ranging from 1 to n, dividing the partition as equally as possible.

+		Immutable
percent_rank() → float

Calculates the relative rank of the current row: (rank - 1) / (total rows - 1).

+		Immutable
rank() → int

Calculates the rank of the current row with gaps; same as row_number of its first peer.

+		Immutable
row_number() → int

Calculates the number of the current row within its partition, counting from 1.

+		Immutable
+ diff --git a/src/current/v23.1/cluster-settings.md b/src/current/v23.1/cluster-settings.md index 1aa538172f8..97f4ac2141d 100644 --- a/src/current/v23.1/cluster-settings.md +++ b/src/current/v23.1/cluster-settings.md @@ -21,7 +21,7 @@ These cluster settings have a broad impact on CockroachDB internals and affect a {% include {{page.version.version}}/sql/sql-defaults-cluster-settings-deprecation-notice.md %} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/settings/settings.html %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/settings/settings.html{% endcapture %}{% include {{ cockroach_include }} %} ## View current cluster settings diff --git a/src/current/v23.1/eventlog.md b/src/current/v23.1/eventlog.md index 2dd3c072d82..e7b813ded9d 100644 --- a/src/current/v23.1/eventlog.md +++ b/src/current/v23.1/eventlog.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/eventlog.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/eventlog.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v23.1/functions-and-operators.md b/src/current/v23.1/functions-and-operators.md index 550ba99eb0a..cd841e81d36 100644 --- a/src/current/v23.1/functions-and-operators.md +++ b/src/current/v23.1/functions-and-operators.md @@ -51,7 +51,7 @@ In addition to the built-in functions described in the following sections, Cockr ## Built-in functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Aggregate functions @@ -61,11 +61,11 @@ For examples showing how to use aggregate functions, see [the `SELECT` clause do Non-commutative aggregate functions are sensitive to the order in which the rows are processed in the surrounding [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#aggregate-functions). To specify the order in which input rows are processed, you can add an [`ORDER BY`]({% link {{ page.version.version }}/order-by.md %}) clause within the function argument list. For examples, see the [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#order-aggregate-function-input-rows-by-column) documentation. {{site.data.alerts.end}} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/aggregates.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/aggregates.md{% endcapture %}{% include {{ cockroach_include }} %} ## Window functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/window_functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/window_functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Operators @@ -137,7 +137,7 @@ The following table lists all CockroachDB operators from highest to lowest prece ### Supported operations -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/operators.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/operators.md{% endcapture %}{% include {{ cockroach_include }} %} {% comment %} ## `CAST()` diff --git a/src/current/v23.1/log-formats.md b/src/current/v23.1/log-formats.md index 7c715f38c89..cfcf8512b19 100644 --- a/src/current/v23.1/log-formats.md +++ b/src/current/v23.1/log-formats.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logformats.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logformats.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v23.1/logging.md b/src/current/v23.1/logging.md index a9b22c4c05f..357817bc212 100644 --- a/src/current/v23.1/logging.md +++ b/src/current/v23.1/logging.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logging.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logging.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v23.2/cluster-settings.md b/src/current/v23.2/cluster-settings.md index 51d72e9054f..e95fe0d7207 100644 --- a/src/current/v23.2/cluster-settings.md +++ b/src/current/v23.2/cluster-settings.md @@ -26,7 +26,7 @@ These cluster settings have a broad impact on CockroachDB internals and affect a {% include {{page.version.version}}/sql/sql-defaults-cluster-settings-deprecation-notice.md %} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/settings/settings.html %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/settings/settings.html{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v23.2/eventlog.md b/src/current/v23.2/eventlog.md index 2dd3c072d82..e7b813ded9d 100644 --- a/src/current/v23.2/eventlog.md +++ b/src/current/v23.2/eventlog.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/eventlog.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/eventlog.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v23.2/functions-and-operators.md b/src/current/v23.2/functions-and-operators.md index 9515f188f77..6fb648e24ff 100644 --- a/src/current/v23.2/functions-and-operators.md +++ b/src/current/v23.2/functions-and-operators.md @@ -51,7 +51,7 @@ In addition to the built-in functions described in the following sections, Cockr ## Built-in functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Aggregate functions @@ -61,11 +61,11 @@ For examples showing how to use aggregate functions, see [the `SELECT` clause do Non-commutative aggregate functions are sensitive to the order in which the rows are processed in the surrounding [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#aggregate-functions). To specify the order in which input rows are processed, you can add an [`ORDER BY`]({% link {{ page.version.version }}/order-by.md %}) clause within the function argument list. For examples, see the [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#order-aggregate-function-input-rows-by-column) documentation. {{site.data.alerts.end}} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/aggregates.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/aggregates.md{% endcapture %}{% include {{ cockroach_include }} %} ## Window functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/window_functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/window_functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Operators @@ -137,7 +137,7 @@ The following table lists all CockroachDB operators from highest to lowest prece ### Supported operations -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/operators.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/operators.md{% endcapture %}{% include {{ cockroach_include }} %} {% comment %} ## `CAST()` diff --git a/src/current/v23.2/log-formats.md b/src/current/v23.2/log-formats.md index 7c715f38c89..cfcf8512b19 100644 --- a/src/current/v23.2/log-formats.md +++ b/src/current/v23.2/log-formats.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logformats.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logformats.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v23.2/logging.md b/src/current/v23.2/logging.md index a9b22c4c05f..357817bc212 100644 --- a/src/current/v23.2/logging.md +++ b/src/current/v23.2/logging.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logging.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logging.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v24.1/cluster-settings.md b/src/current/v24.1/cluster-settings.md index 1d4f9ce0a72..d010bbad362 100644 --- a/src/current/v24.1/cluster-settings.md +++ b/src/current/v24.1/cluster-settings.md @@ -26,7 +26,7 @@ These cluster settings have a broad impact on CockroachDB internals and affect a {% include {{page.version.version}}/sql/sql-defaults-cluster-settings-deprecation-notice.md %} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/settings/settings.html %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/settings/settings.html{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v24.1/eventlog.md b/src/current/v24.1/eventlog.md index 2dd3c072d82..e7b813ded9d 100644 --- a/src/current/v24.1/eventlog.md +++ b/src/current/v24.1/eventlog.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/eventlog.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/eventlog.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v24.1/functions-and-operators.md b/src/current/v24.1/functions-and-operators.md index 9515f188f77..6fb648e24ff 100644 --- a/src/current/v24.1/functions-and-operators.md +++ b/src/current/v24.1/functions-and-operators.md @@ -51,7 +51,7 @@ In addition to the built-in functions described in the following sections, Cockr ## Built-in functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Aggregate functions @@ -61,11 +61,11 @@ For examples showing how to use aggregate functions, see [the `SELECT` clause do Non-commutative aggregate functions are sensitive to the order in which the rows are processed in the surrounding [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#aggregate-functions). To specify the order in which input rows are processed, you can add an [`ORDER BY`]({% link {{ page.version.version }}/order-by.md %}) clause within the function argument list. For examples, see the [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#order-aggregate-function-input-rows-by-column) documentation. {{site.data.alerts.end}} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/aggregates.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/aggregates.md{% endcapture %}{% include {{ cockroach_include }} %} ## Window functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/window_functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/window_functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Operators @@ -137,7 +137,7 @@ The following table lists all CockroachDB operators from highest to lowest prece ### Supported operations -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/operators.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/operators.md{% endcapture %}{% include {{ cockroach_include }} %} {% comment %} ## `CAST()` diff --git a/src/current/v24.1/log-formats.md b/src/current/v24.1/log-formats.md index 7c715f38c89..cfcf8512b19 100644 --- a/src/current/v24.1/log-formats.md +++ b/src/current/v24.1/log-formats.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logformats.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logformats.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v24.1/logging.md b/src/current/v24.1/logging.md index a9b22c4c05f..357817bc212 100644 --- a/src/current/v24.1/logging.md +++ b/src/current/v24.1/logging.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logging.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logging.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v24.2/cluster-settings.md b/src/current/v24.2/cluster-settings.md index 8bb83a25a09..149573f51ab 100644 --- a/src/current/v24.2/cluster-settings.md +++ b/src/current/v24.2/cluster-settings.md @@ -26,7 +26,7 @@ These cluster settings have a broad impact on CockroachDB internals and affect a {% include {{page.version.version}}/sql/sql-defaults-cluster-settings-deprecation-notice.md %} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/settings/settings.html %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/settings/settings.html{% endcapture %}{% include {{ cockroach_include }} %} ## View current cluster settings diff --git a/src/current/v24.2/eventlog.md b/src/current/v24.2/eventlog.md index 2dd3c072d82..e7b813ded9d 100644 --- a/src/current/v24.2/eventlog.md +++ b/src/current/v24.2/eventlog.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/eventlog.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/eventlog.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v24.2/functions-and-operators.md b/src/current/v24.2/functions-and-operators.md index 550ba99eb0a..cd841e81d36 100644 --- a/src/current/v24.2/functions-and-operators.md +++ b/src/current/v24.2/functions-and-operators.md @@ -51,7 +51,7 @@ In addition to the built-in functions described in the following sections, Cockr ## Built-in functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Aggregate functions @@ -61,11 +61,11 @@ For examples showing how to use aggregate functions, see [the `SELECT` clause do Non-commutative aggregate functions are sensitive to the order in which the rows are processed in the surrounding [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#aggregate-functions). To specify the order in which input rows are processed, you can add an [`ORDER BY`]({% link {{ page.version.version }}/order-by.md %}) clause within the function argument list. For examples, see the [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#order-aggregate-function-input-rows-by-column) documentation. {{site.data.alerts.end}} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/aggregates.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/aggregates.md{% endcapture %}{% include {{ cockroach_include }} %} ## Window functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/window_functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/window_functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Operators @@ -137,7 +137,7 @@ The following table lists all CockroachDB operators from highest to lowest prece ### Supported operations -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/operators.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/operators.md{% endcapture %}{% include {{ cockroach_include }} %} {% comment %} ## `CAST()` diff --git a/src/current/v24.2/log-formats.md b/src/current/v24.2/log-formats.md index 7c715f38c89..cfcf8512b19 100644 --- a/src/current/v24.2/log-formats.md +++ b/src/current/v24.2/log-formats.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logformats.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logformats.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v24.2/logging.md b/src/current/v24.2/logging.md index a9b22c4c05f..357817bc212 100644 --- a/src/current/v24.2/logging.md +++ b/src/current/v24.2/logging.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logging.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logging.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v24.3/cluster-settings.md b/src/current/v24.3/cluster-settings.md index 8af2fe82670..e992eca50e4 100644 --- a/src/current/v24.3/cluster-settings.md +++ b/src/current/v24.3/cluster-settings.md @@ -26,7 +26,7 @@ These cluster settings have a broad impact on CockroachDB internals and affect a {% include {{page.version.version}}/sql/sql-defaults-cluster-settings-deprecation-notice.md %} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/settings/settings.html %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/settings/settings.html{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v24.3/eventlog.md b/src/current/v24.3/eventlog.md index 2dd3c072d82..e7b813ded9d 100644 --- a/src/current/v24.3/eventlog.md +++ b/src/current/v24.3/eventlog.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/eventlog.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/eventlog.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v24.3/functions-and-operators.md b/src/current/v24.3/functions-and-operators.md index 9515f188f77..6fb648e24ff 100644 --- a/src/current/v24.3/functions-and-operators.md +++ b/src/current/v24.3/functions-and-operators.md @@ -51,7 +51,7 @@ In addition to the built-in functions described in the following sections, Cockr ## Built-in functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Aggregate functions @@ -61,11 +61,11 @@ For examples showing how to use aggregate functions, see [the `SELECT` clause do Non-commutative aggregate functions are sensitive to the order in which the rows are processed in the surrounding [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#aggregate-functions). To specify the order in which input rows are processed, you can add an [`ORDER BY`]({% link {{ page.version.version }}/order-by.md %}) clause within the function argument list. For examples, see the [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#order-aggregate-function-input-rows-by-column) documentation. {{site.data.alerts.end}} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/aggregates.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/aggregates.md{% endcapture %}{% include {{ cockroach_include }} %} ## Window functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/window_functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/window_functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Operators @@ -137,7 +137,7 @@ The following table lists all CockroachDB operators from highest to lowest prece ### Supported operations -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/operators.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/operators.md{% endcapture %}{% include {{ cockroach_include }} %} {% comment %} ## `CAST()` diff --git a/src/current/v24.3/log-formats.md b/src/current/v24.3/log-formats.md index 7c715f38c89..cfcf8512b19 100644 --- a/src/current/v24.3/log-formats.md +++ b/src/current/v24.3/log-formats.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logformats.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logformats.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v24.3/logging.md b/src/current/v24.3/logging.md index a9b22c4c05f..357817bc212 100644 --- a/src/current/v24.3/logging.md +++ b/src/current/v24.3/logging.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logging.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logging.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v25.1/cluster-settings.md b/src/current/v25.1/cluster-settings.md index 63169bea6cf..775dca5445c 100644 --- a/src/current/v25.1/cluster-settings.md +++ b/src/current/v25.1/cluster-settings.md @@ -26,7 +26,7 @@ These cluster settings have a broad impact on CockroachDB internals and affect a {% include {{page.version.version}}/sql/sql-defaults-cluster-settings-deprecation-notice.md %} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/settings/settings.html %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/settings/settings.html{% endcapture %}{% include {{ cockroach_include }} %} ## View current cluster settings diff --git a/src/current/v25.1/eventlog.md b/src/current/v25.1/eventlog.md index 2dd3c072d82..e7b813ded9d 100644 --- a/src/current/v25.1/eventlog.md +++ b/src/current/v25.1/eventlog.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/eventlog.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/eventlog.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v25.1/functions-and-operators.md b/src/current/v25.1/functions-and-operators.md index 550ba99eb0a..cd841e81d36 100644 --- a/src/current/v25.1/functions-and-operators.md +++ b/src/current/v25.1/functions-and-operators.md @@ -51,7 +51,7 @@ In addition to the built-in functions described in the following sections, Cockr ## Built-in functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Aggregate functions @@ -61,11 +61,11 @@ For examples showing how to use aggregate functions, see [the `SELECT` clause do Non-commutative aggregate functions are sensitive to the order in which the rows are processed in the surrounding [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#aggregate-functions). To specify the order in which input rows are processed, you can add an [`ORDER BY`]({% link {{ page.version.version }}/order-by.md %}) clause within the function argument list. For examples, see the [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#order-aggregate-function-input-rows-by-column) documentation. {{site.data.alerts.end}} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/aggregates.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/aggregates.md{% endcapture %}{% include {{ cockroach_include }} %} ## Window functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/window_functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/window_functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Operators @@ -137,7 +137,7 @@ The following table lists all CockroachDB operators from highest to lowest prece ### Supported operations -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/operators.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/operators.md{% endcapture %}{% include {{ cockroach_include }} %} {% comment %} ## `CAST()` diff --git a/src/current/v25.1/log-formats.md b/src/current/v25.1/log-formats.md index 7c715f38c89..cfcf8512b19 100644 --- a/src/current/v25.1/log-formats.md +++ b/src/current/v25.1/log-formats.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logformats.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logformats.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v25.1/logging.md b/src/current/v25.1/logging.md index a9b22c4c05f..357817bc212 100644 --- a/src/current/v25.1/logging.md +++ b/src/current/v25.1/logging.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logging.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logging.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v25.2/cluster-settings.md b/src/current/v25.2/cluster-settings.md index a4e85a419bf..8f22a3214c2 100644 --- a/src/current/v25.2/cluster-settings.md +++ b/src/current/v25.2/cluster-settings.md @@ -26,7 +26,7 @@ These cluster settings have a broad impact on CockroachDB internals and affect a {% include {{page.version.version}}/sql/sql-defaults-cluster-settings-deprecation-notice.md %} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/settings/settings.html %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/settings/settings.html{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v25.2/eventlog.md b/src/current/v25.2/eventlog.md index 2dd3c072d82..e7b813ded9d 100644 --- a/src/current/v25.2/eventlog.md +++ b/src/current/v25.2/eventlog.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/eventlog.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/eventlog.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v25.2/functions-and-operators.md b/src/current/v25.2/functions-and-operators.md index 9515f188f77..6fb648e24ff 100644 --- a/src/current/v25.2/functions-and-operators.md +++ b/src/current/v25.2/functions-and-operators.md @@ -51,7 +51,7 @@ In addition to the built-in functions described in the following sections, Cockr ## Built-in functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Aggregate functions @@ -61,11 +61,11 @@ For examples showing how to use aggregate functions, see [the `SELECT` clause do Non-commutative aggregate functions are sensitive to the order in which the rows are processed in the surrounding [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#aggregate-functions). To specify the order in which input rows are processed, you can add an [`ORDER BY`]({% link {{ page.version.version }}/order-by.md %}) clause within the function argument list. For examples, see the [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#order-aggregate-function-input-rows-by-column) documentation. {{site.data.alerts.end}} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/aggregates.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/aggregates.md{% endcapture %}{% include {{ cockroach_include }} %} ## Window functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/window_functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/window_functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Operators @@ -137,7 +137,7 @@ The following table lists all CockroachDB operators from highest to lowest prece ### Supported operations -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/operators.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/operators.md{% endcapture %}{% include {{ cockroach_include }} %} {% comment %} ## `CAST()` diff --git a/src/current/v25.2/log-formats.md b/src/current/v25.2/log-formats.md index 7c715f38c89..cfcf8512b19 100644 --- a/src/current/v25.2/log-formats.md +++ b/src/current/v25.2/log-formats.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logformats.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logformats.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v25.2/logging.md b/src/current/v25.2/logging.md index a9b22c4c05f..357817bc212 100644 --- a/src/current/v25.2/logging.md +++ b/src/current/v25.2/logging.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logging.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logging.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v25.3/cluster-settings.md b/src/current/v25.3/cluster-settings.md index 63169bea6cf..775dca5445c 100644 --- a/src/current/v25.3/cluster-settings.md +++ b/src/current/v25.3/cluster-settings.md @@ -26,7 +26,7 @@ These cluster settings have a broad impact on CockroachDB internals and affect a {% include {{page.version.version}}/sql/sql-defaults-cluster-settings-deprecation-notice.md %} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/settings/settings.html %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/settings/settings.html{% endcapture %}{% include {{ cockroach_include }} %} ## View current cluster settings diff --git a/src/current/v25.3/eventlog.md b/src/current/v25.3/eventlog.md index 2dd3c072d82..e7b813ded9d 100644 --- a/src/current/v25.3/eventlog.md +++ b/src/current/v25.3/eventlog.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/eventlog.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/eventlog.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v25.3/functions-and-operators.md b/src/current/v25.3/functions-and-operators.md index 9515f188f77..6fb648e24ff 100644 --- a/src/current/v25.3/functions-and-operators.md +++ b/src/current/v25.3/functions-and-operators.md @@ -51,7 +51,7 @@ In addition to the built-in functions described in the following sections, Cockr ## Built-in functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Aggregate functions @@ -61,11 +61,11 @@ For examples showing how to use aggregate functions, see [the `SELECT` clause do Non-commutative aggregate functions are sensitive to the order in which the rows are processed in the surrounding [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#aggregate-functions). To specify the order in which input rows are processed, you can add an [`ORDER BY`]({% link {{ page.version.version }}/order-by.md %}) clause within the function argument list. For examples, see the [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#order-aggregate-function-input-rows-by-column) documentation. {{site.data.alerts.end}} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/aggregates.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/aggregates.md{% endcapture %}{% include {{ cockroach_include }} %} ## Window functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/window_functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/window_functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Operators @@ -137,7 +137,7 @@ The following table lists all CockroachDB operators from highest to lowest prece ### Supported operations -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/operators.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/operators.md{% endcapture %}{% include {{ cockroach_include }} %} {% comment %} ## `CAST()` diff --git a/src/current/v25.3/log-formats.md b/src/current/v25.3/log-formats.md index 7c715f38c89..cfcf8512b19 100644 --- a/src/current/v25.3/log-formats.md +++ b/src/current/v25.3/log-formats.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logformats.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logformats.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v25.3/logging.md b/src/current/v25.3/logging.md index a9b22c4c05f..357817bc212 100644 --- a/src/current/v25.3/logging.md +++ b/src/current/v25.3/logging.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logging.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logging.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v25.4/cluster-settings.md b/src/current/v25.4/cluster-settings.md index 63169bea6cf..775dca5445c 100644 --- a/src/current/v25.4/cluster-settings.md +++ b/src/current/v25.4/cluster-settings.md @@ -26,7 +26,7 @@ These cluster settings have a broad impact on CockroachDB internals and affect a {% include {{page.version.version}}/sql/sql-defaults-cluster-settings-deprecation-notice.md %} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/settings/settings.html %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/settings/settings.html{% endcapture %}{% include {{ cockroach_include }} %} ## View current cluster settings diff --git a/src/current/v25.4/eventlog.md b/src/current/v25.4/eventlog.md index 2dd3c072d82..e7b813ded9d 100644 --- a/src/current/v25.4/eventlog.md +++ b/src/current/v25.4/eventlog.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/eventlog.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/eventlog.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v25.4/functions-and-operators.md b/src/current/v25.4/functions-and-operators.md index 3da97a7f5fd..80c1485ede8 100644 --- a/src/current/v25.4/functions-and-operators.md +++ b/src/current/v25.4/functions-and-operators.md @@ -51,7 +51,7 @@ In addition to the built-in functions described in the following sections, Cockr ## Built-in functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Aggregate functions @@ -61,11 +61,11 @@ For examples showing how to use aggregate functions, see [the `SELECT` clause do Non-commutative aggregate functions are sensitive to the order in which the rows are processed in the surrounding [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#aggregate-functions). To specify the order in which input rows are processed, you can add an [`ORDER BY`]({% link {{ page.version.version }}/order-by.md %}) clause within the function argument list. For examples, see the [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#order-aggregate-function-input-rows-by-column) documentation. {{site.data.alerts.end}} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/aggregates.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/aggregates.md{% endcapture %}{% include {{ cockroach_include }} %} ## Window functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/window_functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/window_functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Operators @@ -137,7 +137,7 @@ The following table lists all CockroachDB operators from highest to lowest prece ### Supported operations -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/operators.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/operators.md{% endcapture %}{% include {{ cockroach_include }} %} {% comment %} ## `CAST()` diff --git a/src/current/v25.4/log-formats.md b/src/current/v25.4/log-formats.md index 7c715f38c89..cfcf8512b19 100644 --- a/src/current/v25.4/log-formats.md +++ b/src/current/v25.4/log-formats.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logformats.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logformats.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v25.4/logging.md b/src/current/v25.4/logging.md index a9b22c4c05f..357817bc212 100644 --- a/src/current/v25.4/logging.md +++ b/src/current/v25.4/logging.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logging.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logging.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v26.1/cluster-settings.md b/src/current/v26.1/cluster-settings.md index 63169bea6cf..775dca5445c 100644 --- a/src/current/v26.1/cluster-settings.md +++ b/src/current/v26.1/cluster-settings.md @@ -26,7 +26,7 @@ These cluster settings have a broad impact on CockroachDB internals and affect a {% include {{page.version.version}}/sql/sql-defaults-cluster-settings-deprecation-notice.md %} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/settings/settings.html %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/settings/settings.html{% endcapture %}{% include {{ cockroach_include }} %} ## View current cluster settings diff --git a/src/current/v26.1/eventlog.md b/src/current/v26.1/eventlog.md index 2dd3c072d82..e7b813ded9d 100644 --- a/src/current/v26.1/eventlog.md +++ b/src/current/v26.1/eventlog.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/eventlog.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/eventlog.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v26.1/functions-and-operators.md b/src/current/v26.1/functions-and-operators.md index 3da97a7f5fd..80c1485ede8 100644 --- a/src/current/v26.1/functions-and-operators.md +++ b/src/current/v26.1/functions-and-operators.md @@ -51,7 +51,7 @@ In addition to the built-in functions described in the following sections, Cockr ## Built-in functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Aggregate functions @@ -61,11 +61,11 @@ For examples showing how to use aggregate functions, see [the `SELECT` clause do Non-commutative aggregate functions are sensitive to the order in which the rows are processed in the surrounding [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#aggregate-functions). To specify the order in which input rows are processed, you can add an [`ORDER BY`]({% link {{ page.version.version }}/order-by.md %}) clause within the function argument list. For examples, see the [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#order-aggregate-function-input-rows-by-column) documentation. {{site.data.alerts.end}} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/aggregates.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/aggregates.md{% endcapture %}{% include {{ cockroach_include }} %} ## Window functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/window_functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/window_functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Operators @@ -137,7 +137,7 @@ The following table lists all CockroachDB operators from highest to lowest prece ### Supported operations -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/operators.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/operators.md{% endcapture %}{% include {{ cockroach_include }} %} {% comment %} ## `CAST()` diff --git a/src/current/v26.1/log-formats.md b/src/current/v26.1/log-formats.md index 7c715f38c89..cfcf8512b19 100644 --- a/src/current/v26.1/log-formats.md +++ b/src/current/v26.1/log-formats.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logformats.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logformats.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v26.1/logging.md b/src/current/v26.1/logging.md index a9b22c4c05f..357817bc212 100644 --- a/src/current/v26.1/logging.md +++ b/src/current/v26.1/logging.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logging.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logging.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v26.2/cluster-settings.md b/src/current/v26.2/cluster-settings.md index 63169bea6cf..775dca5445c 100644 --- a/src/current/v26.2/cluster-settings.md +++ b/src/current/v26.2/cluster-settings.md @@ -26,7 +26,7 @@ These cluster settings have a broad impact on CockroachDB internals and affect a {% include {{page.version.version}}/sql/sql-defaults-cluster-settings-deprecation-notice.md %} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/settings/settings.html %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/settings/settings.html{% endcapture %}{% include {{ cockroach_include }} %} ## View current cluster settings diff --git a/src/current/v26.2/eventlog.md b/src/current/v26.2/eventlog.md index 2dd3c072d82..e7b813ded9d 100644 --- a/src/current/v26.2/eventlog.md +++ b/src/current/v26.2/eventlog.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/eventlog.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/eventlog.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v26.2/functions-and-operators.md b/src/current/v26.2/functions-and-operators.md index 3da97a7f5fd..80c1485ede8 100644 --- a/src/current/v26.2/functions-and-operators.md +++ b/src/current/v26.2/functions-and-operators.md @@ -51,7 +51,7 @@ In addition to the built-in functions described in the following sections, Cockr ## Built-in functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Aggregate functions @@ -61,11 +61,11 @@ For examples showing how to use aggregate functions, see [the `SELECT` clause do Non-commutative aggregate functions are sensitive to the order in which the rows are processed in the surrounding [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#aggregate-functions). To specify the order in which input rows are processed, you can add an [`ORDER BY`]({% link {{ page.version.version }}/order-by.md %}) clause within the function argument list. For examples, see the [`SELECT` clause]({% link {{ page.version.version }}/select-clause.md %}#order-aggregate-function-input-rows-by-column) documentation. {{site.data.alerts.end}} -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/aggregates.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/aggregates.md{% endcapture %}{% include {{ cockroach_include }} %} ## Window functions -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/window_functions.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/window_functions.md{% endcapture %}{% include {{ cockroach_include }} %} ## Operators @@ -137,7 +137,7 @@ The following table lists all CockroachDB operators from highest to lowest prece ### Supported operations -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/sql/operators.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/sql/operators.md{% endcapture %}{% include {{ cockroach_include }} %} {% comment %} ## `CAST()` diff --git a/src/current/v26.2/log-formats.md b/src/current/v26.2/log-formats.md index 7c715f38c89..cfcf8512b19 100644 --- a/src/current/v26.2/log-formats.md +++ b/src/current/v26.2/log-formats.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logformats.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logformats.md{% endcapture %}{% include {{ cockroach_include }} %} diff --git a/src/current/v26.2/logging.md b/src/current/v26.2/logging.md index a9b22c4c05f..357817bc212 100644 --- a/src/current/v26.2/logging.md +++ b/src/current/v26.2/logging.md @@ -5,4 +5,4 @@ toc: true docs_area: reference.logging --- -{% remote_include https://raw.githubusercontent.com/cockroachdb/cockroach/{{ page.release_info.crdb_branch_name }}/docs/generated/logging.md %} +{% capture cockroach_include %}cockroach-generated/{{ page.release_info.crdb_branch_name }}/logging.md{% endcapture %}{% include {{ cockroach_include }} %}